# Icon component specification The `Icon` component provides a symbol, graphic or image that represents an application, a capability, or some other concept or specific entity with meaning for the user. ## Related variant considerations The following section documents variants of the component that currently exist in Fabric and identifies variants that exist in other component libraries but don't currently exist in Fabric, documenting which component libraries have those variants. ### Variants existing in Fabric today - `Font icons` - `Image icons` ### Variants not in Fabric but that exist in other component libraries - `Block icons` - In Gestalt - `Bordered icons` - In Semantic UI - In Stardust - `Circular icons` - In Semantic UI - In Stardust - `Corner icons` - In Semantic UI - `Focusable icons` - In Chakra UI - `Group icons` - In Semantic UI - `Inverted icons` - In Semantic UI - `Outlined vs filled icons via props` - In Ant Design - `Rotated icons` - In Ant Design - In Semantic UI - In Stardust - `Spinning/Loading icons` - In Ant Design - In Semantic UI - `Two tone icons` - In Ant Design - In Atlaskit ## Reference implementations The following section documents links to different UI libraries implementations of Icons, while also providing a code sandbox with a side by side implementation of them for comparison. - [Side-by-side implementations](https://codesandbox.io/s/icon-implementations-4d5gp) - [Ant Design Icon docs](https://ant.design/components/icon/) - [Atlaskit Icon docs](https://atlaskit.atlassian.com/packages/core/icon) - [Base Web Icon docs](https://baseweb.design/components/icon/) - [Chakra UI Icon docs](https://chakra-ui.com/icon) - [Elemental UI Icon docs](http://elemental-ui.com/forms) - Look for the `Icons` section in the `Forms` page - [Fabric Icon docs](https://developer.microsoft.com/en-us/fabric#/controls/web/icon) - [Gestalt Icon docs](https://pinterest.github.io/gestalt/?ref=designrevision.com#/Icon) - [Material-UI Icon docs](https://material-ui.com/components/icons/) - [Semantic UI Icon docs](https://react.semantic-ui.com/elements/icon/) - [Stardust Icon docs](https://microsoft.github.io/fluent-ui-react/components/icon/definition) ## Props The following section documents the properties that will become part of the new component, as well as the process for mitigating all changes when moving from Fabric and Stardust to Fluent UI. > TODO: Consult the prop wizard to derive consistently defined props. | Name | Type | Default value | Description | | ---- | ---- | ------------- | ----------- | ### Recommended component props | Name | Type | Default value | Description | | ---------------- | :-------: | :-----------: | ------------------------------------------------------------------------------------------------------------------------------------------- | | `ariaHidden` | `boolean` | `false` | Indicates whether the element is exposed to an accessibility API. | | `ariaLabel` | `string` | | Defines a string value that labels the current element. | | `ariaLabelledby` | `string` | | Identifies the element (or elements) that labels the current element. | | `as` | `string` | | Defines a component that should be used as the root element of the `Icon`. | | `className` | `string` | | Defines an additional classname to provide on the root of the `Icon`. | | `name` | `string` | | Defines the name of the pre-registered `Icon` to use. If the string is empty, a placeholder blank space of the same width will be rendered. | | `role` | `string` | | Defines the accessibility role of the `Icon`. | | `title` | `string` | | Specifies extra information about the `Icon`. | ### Props to be discussed None at the moment. ### Fabric Icon props https://developer.microsoft.com/en-us/fabric#/controls/web/icon #### IIconProps interface | Name | Type | Notes | | -------------- | :----------------------------------------------------: | -------------------------------------------------------------------------------- | | `ariaLabel` | `string` | | | `iconName` | `string` | Should we rename this to just be `name`? | | `iconType` | `IconType` | Already deprecated. | | `imageErrorAs` | `React.ComponentType` | Should be removed duo to unnecessary complexity and infrequent use. | | `imageProps` | `IImageProps` | Should not be part of base `Icon`. Should be considered for `ImageIcon` variant. | | `styles` | `IStyleFunctionOrObject` | Should be deprecated in favor of recomposition. | | `theme` | `ITheme` | Should not show up in the public props contract. | ### Stardust Icon props #### IconProps interface | Name | Type | Notes | | --------------- | :-------------: | --------------------------------------------------------------------------------------------------------- | | `accessibility` | `Accessibility` | Why would a user need this prop? | | `bordered` | `boolean` | Should this prop be provided or is this just a matter that could be solved via styling and recomposition? | | `circular` | `boolean` | Should this prop be provided or is this just a matter that could be solved via styling and recomposition? | | `disabled` | `boolean` | Does it make sense for an `Icon` to be `disabled` if it is not an interactive component. | | `name` | `string` | | | `outline` | `boolean` | Should this prop be provided or is this just a matter that could be solved via styling and recomposition? | | `rotate` | `number` | Should this prop be provided or is this just a matter that could be solved via styling and recomposition? | | `size` | `SizeValue` | Should this prop be provided or is this just a matter that could be solved via styling and recomposition? | | `xSpacing` | `IconXSpacing` | Should this prop be provided or is this just a matter that could be solved via styling and recomposition? | ### Conversion process from Fabric 7 to Fluent UI Icon #### IIconProps interface | Name | Action to take/taken | Property transitioned? | Breaking change? | Codemod/Shim created? | | -------------- | ------------------------------------- | :--------------------: | :-------------------------------------: | :-------------------: | | `ariaLabel` | TBD | ❌ | ❌ | ❌ | | `iconName` | TBD | ❌ | ❌ | ❌ | | `iconType` | Removing as it is already deprecated. | ☑ | No, because prop is already deprecated. | ❌ | | `imageErrorAs` | TBD | ❌ | ❌ | ❌ | | `imageProps` | TBD | ❌ | ❌ | ❌ | | `styles` | TBD | ❌ | ❌ | ❌ | | `theme` | TBD | ❌ | ❌ | ❌ | ### Conversion process from Stardust to Fluent UI Icon #### IconProps interface | Name | Action to take/taken | Property transitioned? | Breaking change? | Codemod/Shim created? | | --------------- | -------------------- | :--------------------: | :--------------: | :-------------------: | | `accessibility` | TBD | ❌ | ❌ | ❌ | | `bordered` | TBD | ❌ | ❌ | ❌ | | `circular` | TBD | ❌ | ❌ | ❌ | | `disabled` | TBD | ❌ | ❌ | ❌ | | `name` | TBD | ❌ | ❌ | ❌ | | `outline` | TBD | ❌ | ❌ | ❌ | | `rotate` | TBD | ❌ | ❌ | ❌ | | `size` | TBD | ❌ | ❌ | ❌ | | `xSpacing` | TBD | ❌ | ❌ | ❌ | ## DOM Structure The following section documents the DOM structure for the component from different component library examples and then suggests a recommended DOM taking into consideration common patterns between the libraries reviewed. ### Ant Design Icon #### Example DOM ```html ``` #### Considerations - Only supports SVG icons. ### Atlaskit Icon #### Example DOM ```html ``` #### Considerations - Only supports SVG icons. - To use provided icons you need to import built-in icon directly (i.e. `BookIcon`). ### Base Web Icon #### Example DOM ```html Arrow Up ``` #### Considerations - Only supports SVG icons. - To use provided icons you need to import built-in icon directly (i.e. `ArrowUp`). ### Chakra UI Icon #### Example DOM ```html ``` #### Considerations - Only supports SVG icons. - Icons are and can be added as part of the theme. ### Fabric Icon #### Example DOM ##### Font Icon ```html ``` ##### SVG Icon ```html ``` ##### Image Icon ```html ``` #### Considerations - Requires icon initialization and uses global registration. ### Gestalt Icon #### Example DOM ```html ``` #### Considerations - Only supports SVG icons. - Renders by default as a block, and not an inline, element. ### Material-UI Icon #### Example DOM ##### Font Icon ```html ``` ##### SVG Icon ```html ``` #### Considerations None. ### Semantic UI Icon #### Example DOM ```html ``` #### Considerations - Only supports font icons. - Can support icon groups and icon superpositions with the second item in the corner. ### Stardust Icon #### Example DOM ```html ``` #### Considerations - Allows for both font and SVG icons but only has SVG icons built-in. ### Recommended DOM After looking at all the component libraries above and taking into consideration common patterns the following DOM is recommended. ```html ``` > TODO: Discuss need to shim back to Fabric with `as=i` because of different tag being used in order to not break styling. ### Slots From the recommended DOM above we can indicate which slots are going to be required: | Name | Considerations | | ------ | -------------- | | `root` | | > TODO: I really think we should have `ImageIcon` as a separate component, maybe via recomposition, to have a very simple and fast base `Icon`. > TODO: Do we want a specific `SvgIcon` apart from the `ImageIcon` variant? This seems like one of the most used examples. ## Behaviors Aria spec: There's no aria spec available for icons. Fluent UI HIG: https://microsoft.sharepoint-df.com/:w:/r/teams/OPGUXLeads/_layouts/15/Doc.aspx?sourcedoc=%7B5113018C-05E7-44BF-B6D4-B164755B8D71%7D&file=Icon.docx&action=default&mobileredirect=true ### States The following section describes the different states in which a `Icon` can be throughout the course of interaction with it. #### Default state An `Icon` has only one state, its default state. The `Icon` is not an interactive component and it's used only for representational purposes. #### States that need discussion None. ### Keyboard interaction There is no keyboard interaction that occurs with the `Icon`. ### Cursor interaction There is no cursor interaction that occurs with the `Icon`. ### Touch interaction There is no touch interaction that occurs with the `Icon`. ### Screen reader accessibility #### `root`: - Should not be tabbable nor focusable and should have `aria-hidden` applied to it by default. #### Accessibility concerns for the user. All accessibility concerns would come from user manipulation of the component, so they would be a concern solely for the user and not for the component creator. ## Themability and customization ### Composition The `Icon` component uses `react-texture` to provide a recomposable implementation that has no runtime performance penalties. The `BaseIcon` implementation can be used to provide new `slots` and default `props` without the application of additional styling: ```tsx const FooIcon = BaseIcon.compose({ tokens: {}, styles: {}, slots: {} }); render () { } ``` ### Icon Registration #### Fabric Fabric uses global registration for its icons which needs a call to an initialization function to be used. Below are wiki and code references into this process: - [Wiki page](https://github.com/microsoft/fluentui/wiki/Using-icons) - [Icon font generation tool](https://uifabricicons.azurewebsites.net) - [Main `initializeIcons` function](https://github.com/microsoft/fluentui/blob/master/packages/icons/src/index.ts) - [Icon registration utilities](https://github.com/microsoft/fluentui/blob/master/packages/styling/src/utilities/icons.ts) - [Icon component](https://github.com/microsoft/fluentui/tree/master/packages/office-ui-fabric-react/src/components/Icon) #### Stardust Stardust registers icons in the theme, with all default icons being SVGs but also supporting font icons via: ```ts type ObjectOrFunc = ((arg: TArg) => TResult) | TResult; type FontIconSpec = ObjectOrFunc<{ content: string; fontFamily: string; }>; ``` Below are wiki and code references into this process: - [SVG icon processing](https://github.com/microsoft/fluent-ui-react/blob/21c2f9e3e495b3094e0db4610e9f8834cdc135b0/packages/react/src/themes/teams/components/Icon/svg/ProcessedIcons/stardust-icons.sh#L36) - [Instructions on adding new SVG Icon](https://github.com/microsoft/fluent-ui-react/pull/585) - [Font icon registration into the theme (fontAwesome theme example)](https://github.com/microsoft/fluent-ui-react/blob/feat/generate-css/src/themes/teams/components/Icon/fontAwesomeIconStyles.ts) - [Font vs SVG icon rendering](https://github.com/microsoft/fluent-ui-react/blob/master/packages/react/src/themes/teams/components/Icon/iconStyles.ts) - [Icon styles as part of theme component styles](https://github.com/microsoft/fluent-ui-react/blob/de10e334fc039370c4fe4b425050327d57f3f515/packages/react/src/themes/teams/componentStyles.ts#L51) - [Merging icons as part of theme](https://github.com/microsoft/fluent-ui-react/blob/feat/generate-css/src/themes/teams/index.ts) > - TODO: Decide on recommended thing to do. Leaning towards Stardust approach but worried about perf implications regarding icon definitions. > - TODO: Discuss how to handle font loading if we put icons in the theme. > - Should font loading also be part of the theme? > - Has to be loaded somehow and is ok for the majority of customers to automatically load them, but some customers need to prevent this loading from MSFT CDNs. ## Class names 1 per slot 1 per state, tagged on root ### Component design tokens > Tokens represent the general look and feel of the various visual slots. Tokens feed into the styling at the right times in the right slot. > > Regarding naming conventions, use a camelCased name following this format: > `{slot}{property}{state (or none for default)}`. For example: `thumbSizeHovered`. > > Common property names: `size`, `background`, `color`, `borderRadius` > > Common states: `hovered`, `pressed`, `focused`, `checked`, `checkedHovered`, `disabled` | Name | Considerations | | ------------ | -------------- | | `color` | | | `fontSize` | | | `fontWeight` | | ## Use cases > TODO: Example use cases ## Compatibility with other libraries > TODO: If this component represents a selected value, how will that be used in an HTML form? Is there a code example to illustrate? > TODO: Is it possible this component could be rendered in a focus zone? If so, should the focus model change in that case?