This tool allows you to browse Office UI Fabric's icons, and use it to create and maintain subsets of the icon font to use in your web apps.
Contents
- What is Office UI Fabric?
- What is a font subset and why should I use one?
- How to use the tool
- Get started with your subset
- How to use icon subsets
- Maintaining a subset
- Providing feedback
What is Office UI Fabric?
Office UI Fabric is the official front-end framework and design system for building experiences that fit seamlessly into Office and Office 365. Its two primary in-code projects, Fabric Core and Fabric React, contain atomic styles and React.js components, respectively, that allow you to use Microsoft's design language in your own web application that builds on a Microsoft platform.
Fabric uses a custom icon font that contains over 1400 glyphs that you can scale, color, and style in any way. Both Fabric Core and Fabric React contain CSS/SCSS styles and JavaScript APIs for using these icons in code, and this tool produces SCSS and TS files that follow the same format and conventions for each. In other words, font subsets produced by this tool can be used as drop-in replacements for the default icon sets in Fabric Core and Fabric React.
However, note that the tool only generates webfonts that can be used in your application. To download an icon font that you can install locally in order to use Fabric's design toolkits, see Fabric's design downloads page.
Note that your use of the icons generated by the Fabric Icons tool are subject to the terms of the Fabric assets license.
What is a font subset and why should I use one?
As the name implies, a font subset contains a portion of the complete set of characters included in a font. This is useful for fonts like Office UI Fabric's icon font, which includes far more characters than what any single application will need or should serve at once (>1000 characters, which is ~150KB for the .woff). Using a subset ensures that an application is only using the glyphs it needs at any given time, which saves significant bytes over the wire.
The instructions below will help familiarize you with the tool, and get started using it in your application.
The tool uses a simple UI to search, browse, and select icons.
The Command Bar lets you search the icon list, choose the view mode of the icon list (either List or Grid) and generate a subset from the current selection. A counter keeps track of how many icons you've selected, and lets you clear the current selection when invoked.
The Details Pane provides information about & configuration for the current subset. Text boxes for font name and font-family let you configure additional aspects of your subset.
Font name is the value given to each of the built files in the subset,
Font-family is the value given to the font-family
in the @font-face
definition for your subset. Change this from the default, 'FabricMDL2Icons'
, if your icon set might conflict with another definition of Fabric (for example, if you're hosting two instances of Fabric in a given page, or using Fabric in a SharePoint webpart).
File size previews give an approximation of the final size of the generated files in your subset. It's important to note that these sizes are just an estimate and are impacted by how much path data is in each selected character (for example, a solid filled square will take up more space than an outlined square).
Try selecting a few icons by clicking individual characters or by dragging a marquee to select several at once. Once you've selected some icons, click "Get subset" in the Command Bar, then click "OK" in the dialog that pops up to generate a .zip containing your subset package. Once you've downloaded and extracted the package, go to "Get started with your subset".
Get started with your subset
Folder structure
Each subset package will include some variation of the following files, assuming a font name of fabric-icons
(which can be configured in the tool—see Font config options below). Note that if "Create subset chunks" was selected when generating a subset, there will be an additional HTML, JSON, CSS, SCSS, and TS file for each generated "chunked" subset.
fabric-icons
│-- README.md: Docs for the subset package.
│-- microsoft-ui-fabric-assets-license.pdf: License and usage terms for the fonts.
│-- fabric-icons.html - Demo HTML for a given subset.
│
└─── config
│ │-- fabric-icons.json - Configuration file for the subset package.
| > Contains the list of icon names to be included as well as options for
| > the subset itself. See the section below on "maintaining a subset"
| > for more details.
│
└─── css
| │-- fabric-icons.css - @font-face definition and icon classes for the subset. Links to the subsetted font file.
| │-- fabric-icons-inline.css - Same as standard CSS, but includes the base64-encoded WOFF font file inline.
│
└─── scss
| │-- fabric-icons.scss - Same as standard CSS and adds a mixin for each icon.
| │-- fabric-icons-inline.scss - Same as standard SCSS, but includes the base64-encoded WOFF font file inline.
│
└─── fonts
| │-- fabric-icons.woff - The subsetted icon font.
│
└─── src
| │-- index.ts - Contains top-level exports for all subset initialization code.
| │-- fabric-icons.ts - TypeScript subset options and initialization code.
| │-- IconNames.ts - Contains const enum of all available icon names for Intellisense.
| │-- iconAliases.ts - Contains aliases for icons that have been renamed or would cause issues in JavaScript.
How to use icon subsets
The icon subsets included here are based on the CSS and SCSS approaches of office-ui-fabric-core (see the icons page on the Fabric website), and TypeScript-based approach of @uifabric/icons
, which is what's used in office-ui-fabric-react. Each subset can be used independently of either of those projects, meaning your app doesn't need to have them installed in order to use the icon subsets in this package. The instructions here will help you get started quickly using each subset method, but you should refer to the full documentation for each for more detail.
Which subset should I use?
CSS and SCSS subsets
The CSS and SCSS methods are similar to what's used in office-ui-fabric-core, which is useful for quickly applying Microsoft's design language to an HTML and CSS-based web app. Both include class names you can use in plain HTML, and differ only in that the SCSS files require a SASS preprocessor to use its icon mixins and build its output into plain CSS.
Use the CSS subset if your app is relatively simple (e.g. no build process) or you aren't already using SCSS. Simply add a link to one of the icons CSS files to your page, or @import
it into another CSS file, and add the icon classes to HTML elements like so:
css
<i class="ms-Icon ms-Icon--Edit"></i>
Use the SCSS subset if your app already uses SCSS in a build pipeline, or you wish to use the icon mixins to inject the icon code into your own class names.
For example, if you wish to use the same Edit icon as before but without using the standard .ms-Icon--Edit
class, you can use the mixins to inject the icon code into a custom class like so:
.myClassName:before { @include ms-Icon--Edit }
This would result in the following code being generated:
.myClassName:before { content: "\E70F"; }
You may wish to use this approach if there may be multiple versions of Fabric on the page and you want to ensure there won't be any rendering conflicts. However, be sure to either add the .ms-Icon
class to those elements or @include ms-Icon
in your custom class name as this sets the @font-family
to the font in your subset.
TypeScript subsets
The TypeScript subset method included under src
is similar to what's used in @uifabric/icons
and will make the most sense in applications that use office-ui-fabric-react controls.
As a prerequisite to using these subsets, ensure that your project is configured to build TypeScript. You may wish to use a tool like create-react-app-typescript or Microsoft's own TypeScript-React-Starter. This is a temporary limitation—future updates to the subsetter tool will include pre-compiled subsets that you'll be able to use with simpler configurations.
Once your project is configured, in your source code, import the initializeIcons
function and call it on the page(s) you wish to use the icons:
import { initializeIcons } from 'path-to-subset/src';
initializeIcons('path/to/fonts');
This defines an @font-face
rule and registers a map of icon names for the subset. Once initialized, icons can be used through the getIcon
API in office-ui-fabric-react
, like below:
import { Icon } from 'office-ui-fabric-react/lib/Icon';
<Icon iconName='Snow' />
CSS classnames can also be used directly on elements using the getIconClassNames
API from @uifabric/styling
:
import { getIconClassName } from '@uifabric/styling';
return `<i class="${getIconClassName('Snow')}" />`;
More details on JavaScript-based icon usage can be found on Office UI Fabric React's wiki, @uifabric/icons
, and @uifabric/styling
.
Maintaining a subset
Each subset package has a configuration JSON file that describes which icons are included in that subset and which options were selected for the subset, such as chunkSubsets
or excludeGlyphs
. This file is used to maintain and update the subset over time--it can be dragged and dropped on to the Fabric Icons tool to pre-populate icon selection and whichever options were chosen in the tool.
It is recommended to check this file in to a project's source control and update it each time you make changes to a subset.
Most options map to a text field or checkbox in the "Subset options" section of the details pane. This is represented by the "Tool label" column below.
Font config options
Option | Default value | Tool label | Description |
---|
fontName | 'fabric-icons' | Font file name | The name given to each of the subset's HTML, CSS, SCSS, TS, and JSON files. |
fontFamilyName | 'FabricMDL2Icons' | Font-family name | The name of the font-family given in the @font-face definition for the subset. It is recommended to change this only if the icon subset will be used in conjunction with multiple, different versions of Fabric or other icon subsets on the same page. |
excludeGlyphs | false | Exclude selection from subset | Produces a subset that excludes the selected glyphs from the full Fabric icon set. This is useful if you wish to create a subset that includes all of the Fabric icons EXCEPT for the selected icons. |
chunkSubsets | false | Create subset chunks | Controls whether to produce additional subsets that can be loaded on-demand. |
hashFontFileName | true | Hash font file name | Controls whether to add a unique hash to the .woff font file based on glyph selection and subset options. This is useful for CDN cache busting if you plan on hosting font files on a CDN, which may serve old cached versions of a font without a busting mechanism. |
glyphs | [{ }] | N/A | The list of icons included in a subset, populated from selecting icons in the Fabric Icons tool. Each glyph is an object with a name and unicode property. |
Providing feedback
If you run into any issues, have feedback to share, or have any questions on the tool, please file an issue in Fabric React. Be sure to include [Icon Tool] in the title so we can get the right folks looped in.