or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-uifabric--icons

Fluent UI React icon set providing 1800+ icons with font-based rendering and CDN support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@uifabric/icons@7.9.x

To install, run

npx @tessl/cli install tessl/npm-uifabric--icons@7.9.0

index.mddocs/

@uifabric/icons

@uifabric/icons provides a comprehensive collection of 1800+ icons for Fluent UI React applications. It offers a centralized icon management system through the initializeIcons function that registers all icons and loads font resources from configurable CDN endpoints, with built-in support for custom base URLs and on-demand icon loading.

Package Information

  • Package Name: @uifabric/icons
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @uifabric/icons

Core Imports

import { initializeIcons } from "@uifabric/icons";

For type-safe icon names:

import { initializeIcons, IconNames, IconNamesInput } from "@uifabric/icons";

CommonJS:

const { initializeIcons } = require("@uifabric/icons");

Basic Usage

import { initializeIcons } from "@uifabric/icons";
import { Icon } from "@fluentui/react/lib/Icon";

// Initialize with default Office CDN
initializeIcons();

// Use icons in React components
<Icon iconName="Mail" />
<Icon iconName="People" />
<Icon iconName="Settings" />
import { initializeIcons } from "@uifabric/icons";
import { getIconClassName } from "@uifabric/styling";

// Initialize with custom CDN
initializeIcons("https://my.cdn.com/path/to/icons/");

// Use icons via CSS classes
const mailIcon = getIconClassName("Mail");
return `<i class="${mailIcon}" />`;

Architecture

@uifabric/icons is built around several key components:

  • Icon Registration System: Centralized icon registry that loads font definitions on demand
  • Font-Based Rendering: Uses web fonts with Unicode mappings for optimal performance and scalability
  • CDN Flexibility: Supports both Office CDN and custom CDN endpoints for font delivery
  • Modular Loading: Icons are split across 19 font subset modules for optimized loading (1 primary + 18 numbered subsets)
  • Global Configuration: Page-level configuration via window.FabricConfig to avoid race conditions
  • Icon Aliasing: Built-in alias system for backwards compatibility and common naming variations

Capabilities

Icon Initialization

Core function that registers all available icons and configures font loading from CDN endpoints.

/**
 * Initializes all Fluent UI icons by registering font subsets and configuring CDN endpoints
 * @param baseUrl - Base URL for icon font files (defaults to Office CDN or window.FabricConfig)
 * @param options - Optional icon configuration from @uifabric/styling
 */
function initializeIcons(
  baseUrl?: string,
  options?: IIconOptions
): void;

/**
 * Configuration options for icon initialization
 */
interface IIconOptions {
  /** Disable console warnings for missing icons */
  disableWarnings?: boolean;
  /** Enable warnings when icons are not found */
  warnOnMissingIcons?: boolean;
}

Usage Examples:

import { initializeIcons } from "@uifabric/icons";

// Use default Office CDN
initializeIcons();

// Use custom CDN endpoint
initializeIcons("https://my.cdn.com/assets/icons/");

// With configuration options
initializeIcons(undefined, {
  disableWarnings: true,
  warnOnMissingIcons: false
});

Global Configuration

Configure icon loading behavior before script initialization to avoid race conditions.

declare global {
  interface Window {
    /**
     * Global configuration object for Fluent UI icon loading
     */
    FabricConfig?: {
      /**
       * Base URL for font files (legacy, use iconBaseUrl instead)
       */
      fontBaseUrl?: string;
      /**
       * Base URL for icon font files (preferred over fontBaseUrl)
       */
      iconBaseUrl?: string;
    };
  }
}

Usage Examples:

<!-- Configure before loading scripts -->
<script>
  window.FabricConfig = {
    iconBaseUrl: "https://my.cdn.com/icons/"
  };
</script>
<script src="your-app-bundle.js"></script>
// Check configuration at runtime
const win = getWindow();
const baseUrl = win?.FabricConfig?.iconBaseUrl || 
                win?.FabricConfig?.fontBaseUrl || 
                DEFAULT_BASE_URL;

Icon Alias System

Built-in alias system for backwards compatibility and common naming variations.

/**
 * Registers common icon aliases for backwards compatibility
 * Called automatically by initializeIcons()
 */
function registerIconAliases(): void;

Available Icon Aliases:

// Common aliases registered by default
'trash' → 'delete'
'onedrive' → 'onedrivelogo'
'alertsolid12' → 'eventdatemissed12'
'sixpointstar' → '6pointstar'
'twelvepointstar' → '12pointstar'
'toggleon' → 'toggleleft'
'toggleoff' → 'toggleright'

Usage Examples:

import { getIconClassName } from "@uifabric/styling";
import { initializeIcons } from "@uifabric/icons";

// Initialize icons (includes alias registration)
initializeIcons();

// Use aliases - these work the same as the target icons
const trashIcon = getIconClassName("trash");    // Same as "delete"
const toggleIcon = getIconClassName("toggleon"); // Same as "toggleleft"

Icon Name Types

Type-safe icon naming system providing compile-time validation of icon names.

/**
 * @deprecated Const enum use is deprecated. See GitHub issue #7110
 * Comprehensive enum containing all available icon names
 */
export const enum IconNames {
  PageLink = "PageLink",
  CommentSolid = "CommentSolid",
  ChangeEntitlements = "ChangeEntitlements",
  Installation = "Installation",
  ChevronDown = "ChevronDown",
  ChevronUp = "ChevronUp",
  Edit = "Edit",
  Add = "Add",
  Cancel = "Cancel",
  More = "More",
  Settings = "Settings",
  Mail = "Mail",
  People = "People",
  Phone = "Phone",
  Pin = "Pin",
  Shop = "Shop",
  // ... 1800+ more icon names
}

/**
 * Type representing valid icon name strings (union of all IconNames keys)
 * Use this type for parameters that accept icon names
 */
export type IconNamesInput = keyof typeof IconNames;

Usage Examples:

import { IconNames, IconNamesInput } from "@uifabric/icons";
import { Icon } from "@fluentui/react/lib/Icon";

// Using enum (deprecated but available)
<Icon iconName={IconNames.Mail} />

// Using type-safe string parameter
function MyIconComponent({ iconName }: { iconName: IconNamesInput }) {
  return <Icon iconName={iconName} />;
}

// Type-safe function parameter
function createIconElement(name: IconNamesInput): string {
  return getIconClassName(name);
}

Integration with Fluent UI

React Icon Component

import { Icon } from "@fluentui/react/lib/Icon";
import { initializeIcons } from "@uifabric/icons";

// Initialize icons first
initializeIcons();

// Use in components
function MyComponent() {
  return (
    <div>
      <Icon iconName="Mail" />
      <Icon iconName="People" />
      <Icon iconName="Settings" />
    </div>
  );
}

CSS Class Generation

import { getIconClassName } from "@uifabric/styling";
import { initializeIcons } from "@uifabric/icons";

// Initialize icons first
initializeIcons();

// Generate CSS classes for manual rendering
const mailClass = getIconClassName("Mail");
const settingsClass = getIconClassName("Settings");

// Use in HTML
return `
  <i class="${mailClass}" aria-label="Mail"></i>
  <i class="${settingsClass}" aria-label="Settings"></i>
`;

Available Icons

The package includes 1800+ icons organized into categories:

Common Icons:

  • Navigation: ChevronDown, ChevronUp, ChevronLeft, ChevronRight
  • Actions: Add, Edit, Delete, Cancel, More, Settings
  • Communication: Mail, Phone, People, Share
  • Files: Folder, Upload, Download, Page
  • UI Elements: Search, Filter, Sort, View, Clear

Business Icons:

  • Office Apps: Word, Excel, PowerPoint, OneNote, Teams
  • SharePoint: Lists, Libraries, Sites, Pages
  • Productivity: Calendar, Tasks, Notes, Bookmarks

Technical Icons:

  • Development: Code, Database, Server, Cloud
  • System: Settings, Admin, Security, Permissions
  • Status: Success, Warning, Error, Info

To see all available icons, explore the IconNames enum or refer to the Fluent UI Icon Gallery.

Font Loading Details

Icons are delivered through web fonts split into 19 optimized subsets:

  • Primary Font: FabricMDL2Icons (fabric-icons.ts) - Core navigation and common icons
  • Subset Fonts: FabricMDL2Icons-0 through FabricMDL2Icons-17 - Themed and specialized icons (18 additional subsets)
  • Format: WOFF font format for broad browser support
  • Loading: On-demand loading when icons are referenced
  • CDN: Default Office CDN (https://res.cdn.office.net/files/fabric-cdn-prod_20241209.001/assets/icons/) with fallback support for custom endpoints

Error Handling

The package handles common error scenarios:

// Missing baseUrl - falls back to default CDN
initializeIcons(); // Uses Office CDN

// Invalid CDN URL - fonts may fail to load but won't crash
initializeIcons("https://invalid-cdn.com/");

// Missing icon names - handled by @uifabric/styling
const className = getIconClassName("NonExistentIcon"); // Returns fallback class

Dependencies

Required peer dependencies from the Fluent UI ecosystem:

// From @uifabric/styling
import { IIconOptions, IIconSubset, registerIcons, registerIconAlias } from "@uifabric/styling";

// From @uifabric/utilities  
import { getWindow } from "@uifabric/utilities";

// From @uifabric/set-version
import { setVersion } from "@uifabric/set-version";

These dependencies are automatically available when using @uifabric/icons in a Fluent UI React application.