• Font-based icons
  • Alternative CDN options
  • Creating an icon subset
  • What does initializeIcons do?
  • Registering custom icons
  • Disabling warnings
    • Test scenarios
    • Library icon registration

By default, the font-based Fluent UI icons are not added to your bundle or loaded on the page, in order to save bytes for scenarios where you don't care about icons, or you only care about a subset.

To make the icons available, you may initialize them as follows. Note that initializeIcons() should only be called once per app and must be called before rendering any components. This is typically done in the app's top-level file just before the main ReactDOM.render() call.

// Also available from @uifabric/icons (7 and earlier) and @fluentui/font-icons-mdl2 (8+)
import { initializeIcons } from '@fluentui/react/lib/Icons';

initializeIcons(/* optional base url */);

By default, the icon fonts for the default set of icons will be pulled from the SharePoint CDN. The default endpoint is spoprod-a.akamaihd.net, but if you run into access/security issues from the Akamai domain, you can also pass in https://static2.sharepointonline.com/files/fabric/assets/icons/ as the baseUrl.

If you would like the icons to be served from your own CDN, simply copy the files from @uifabric/icons/fonts (or @fluentui/font-icons-mdl2/fonts in version 8+) to your CDN. A build step is recommended to automate this. Then, in initializeIcons, provide the base URL to access those fonts. Note that it will require a trailing slash.

(If you're using custom icons as described under "Registering custom icons" below, you don't need to modify the CDN setting.)

The Fabric Icons tool, https://aka.ms/uifabric-icons, lets you search and browse all of Fabric/Fluent UI's MDL2 icons. You can also use it to create and maintain subsets of the icon font to use in your web apps, which are drop-in replacements for the default Fabric Core and Fluent UI React icon sets. In addition, the Fabric Icons tool is updated with new icons several times a month, whereas the default Fluent UI React set is updated only occasionally. You can see detailed docs for the tool at https://aka.ms/uifabric-icons?help.

Note that if you use the Fabric icons tool to create your own icon subset, you will also need to host those assets on your own CDN.

It registers a map of icon names, which define how to render icons. Icons can be rendered either through JSX components, or as a font character. The icon code will register the font-face definition only when a given icon from a subset is referenced.

What we're trying to optimize here is download size. We define a map of icon codes which map to a font-face. When the Icon component renders the Upload icon, we determine if the font-face has yet been registered, an if not, we add it to the page, causing the subset containing the Upload icon to be downloaded.

The @uifabric/icons package (or @fluentui/font-icons-mdl2 in version 8+) can resolve over 1000 different icons, and will download from the 10+ font partitions, minimizing download overhead. We also include the most common icons in the first partition, optimizing for the basic scenarios. If there are commonly used icons missing in there, please file an issue so that we can evaluate adjusting the primary partition.

If you want to use a different icon font or SVG icons, you can use registerIcons to add custom icons.

SVG icons, such as the ones from @fluentui/react-icons-mdl2, can be registered as follows:

import { registerIcons } from '@fluentui/react/lib/Styling';
import { ChevronDownIcon } from '@fluentui/react-icons-mdl2';

registerIcons({
  icons: {
    ChevronDown: <ChevronDownIcon />
  }
});

You can then use those icons anywhere you'd normally use icons, such as the Icon component or in iconProps:

import { Icon } from '@fluentui/react/lib/Icon';

const IconTest = () => <Icon iconName="ChevronDown" />;

You can also use this with custom font families:

import { registerIcons } from '@fluentui/react/lib/Styling';

registerIcons({
  fontFace: {
    fontFamily: `"CustomFontFamily"`
  },
  icons: {
    Up: '\uE417',
    Down: '\uE416'
  }
});

When icons are rendered using the Icon component, but have not yet been registered, you will see console errors indicating so. In most cases, this can be addressed by registering the icons. But there are 2 cases, where this isn't desirable:

In test scenarios, you may want to simply disable the warnings and avoid registering icons. To do this:

import { setIconOptions } from '@fluentui/react/lib/Styling';

// Suppress icon warnings.
setIconOptions({
  disableWarnings: true
});

If your code is running in an environment where icons may have already been registered, you may need to disable the warnings. (By default, registering the same icon twice will ignore subsequent registrations.) To initialize icons and avoid duplication warnings, pass options into initializeIcons:

import { initializeIcons } from '@fluentui/react/lib/Icons';

initializeIcons(undefined, { disableWarnings: true });