Icon

IconName is the name of a glyph in the built-in Fabric MDL2 set, and the iconography page is where all 2,300 of them are listed and searchable. IsEnabled draws the icon in the disabled color of whatever role it is painted in, which is how an icon standing for something unavailable stops looking actionable.

Disabled

Variant decides how much of the icon's color is painted. Text, the default, is the glyph alone with no box around it and no padding, which is what an icon sitting inside a sentence or beside a label should be. Outline and Fill put the glyph in a box of its own - a rule around it, or the role's color behind it with the glyph reversed out - which is how an icon becomes a badge that stands on its own. Circular rounds that box all the way and squares it off at the same time, so a narrow glyph and a wide one are drawn in circles of the same size - the shape of a status dot or an avatar placeholder.

Disabled

Circular

Rotate turns the glyph by a quarter, a half or three quarters of a turn, RotateAngle turns it by any angle in degrees (negative for counter-clockwise, and it replaces Rotate when both are given), and Flip mirrors it on either axis or both. All three are drawn as one transform, so they combine rather than cancel each other out - which is what lets one arrow glyph stand in for all eight directions instead of eight glyphs - and they are written with the individual rotate and scale properties, so an Animation can play on top of them. FlipRtl is the one to reach for in a bilingual app: it mirrors the icon only where the writing runs right-to-left, following the direction of the rendered document rather than a parameter, and it multiplies with an explicit Flip rather than replacing it. Give it to a glyph that points somewhere - an arrow, a chevron, a reply - and never to a clock, a checkmark or a media rewind button, none of which mirror in RTL.

Rotate

RotateAngle

Flip

FlipRtl (the second row is the same icon inside a right-to-left container)

Animation sets the icon looping. Spin and SpinReverse turn it at the speed of every other loader in the library, Pulse ticks it around in eight steps the way a segmented spinner does, and Beat, BeatFade, Fade, Shake and Bounce draw the eye to something that just changed or needs attention. Each of them is a claim that something is still happening, so none of them belongs on an icon that is merely decorative. They all slow down instead of stopping when the reader has asked for reduced motion, and ForceAnimation restores their full speed for an icon whose motion carries the meaning. AnimationDuration replaces the length of one cycle with a CSS time of your own - the reduced motion factor still multiplies it - AnimationDelay holds the icon still for a CSS time before the first cycle, which is what turns a row of identical icons into a wave, and the turn a Rotate, a RotateAngle or a Flip gives the icon is drawn beside the animation rather than under it, so a mirrored arrow still spins.

AnimationDuration, and a turn the animation plays on top of

AnimationDelay: the same animation on three icons, each starting a little after the one before it

The glyphs of an icon font are not all the same width, which is what makes the labels of a menu or a nav start at a different place on every row. FixedWidth gives every icon the same box and centers the glyph inside it, so the labels line up. The first list below is without it and the second with it.

OnClick turns the icon into a real control: it joins the tab order, shows the focus ring, reacts to the pointer on hover and while it is pressed, answers Enter and Space as well as the pointer without letting Space scroll the page under it, and is announced as a button. A small glyph is also a small target, so the area that answers the pointer is grown to the 24 by 24 pixels WCAG asks of one while the icon keeps the size it was given. Because it is announced as a button it needs a name, so give it an AriaLabel or a Title; and because a disabled control still has to be found by whatever pointed at it, an icon with IsEnabled false leaves the tab order and refuses the click rather than disappearing - and keeps answering the pointer, so the Title saying why the action is unavailable is still there to be read. It is still an icon and not a BitButton - there is no label, no pressed state and no busy state - so reach for a button whenever the action deserves one.

Clicked 0 times.

Anything put inside the icon is rendered in place of a glyph, which is how a set that is neither a font nor a class - an inline SVG, a sprite reference, a picture - still gets the icon's color, size and variant. An SVG drawn with fill="currentColor" follows the color role exactly as a glyph does, and FontSize or Size scales it as long as its own dimensions are given in em. A glyph sits on the baseline the way a letter does, but an SVG or an image is aligned by the bottom edge of its box and rides high next to the text around it; Inline is the quarter of an em that drops it back onto the line.

Aligned by its box and dropped onto the line with Inline

An icon is decorative until something names it. Left unnamed it carries aria-hidden and no role, so a screen reader skips it - which is right for the overwhelming majority of icons, since they sit beside a label that already says the same thing, and an unnamed image is a node a reader stops at with nothing to read out. AriaLabel names it for assistive technology only, Title names it and shows a native tooltip on hover as well, and an aria-labelledby of your own names it from somewhere else on the page. Any of the three gives the icon the img role and takes the hiding away. Give one of them to an icon that is the only thing carrying its meaning - a status dot, an icon-only control - and to nothing else. A native tooltip never appears for a keyboard or a touch user, so use a BitTooltip when the text is meant to be seen rather than only read out.

Color paints the icon in one of the theme's roles rather than in a literal color, so every preset and both schemes re-skin it. The first eight are the semantic roles - the ones that mean something, and that a status or a validation icon should be painted in - while the background, foreground and border roles are the neutral tiers of the surface itself, for an icon that has to sit on a colored panel or match the text around it.

Primary

Secondary

Tertiary

Info

Success

Warning

SevereWarning

Error

   




   




   

PrimaryForeground

SecondaryForeground

TertiaryForeground

PrimaryBorder

SecondaryBorder

TertiaryBorder

Icon takes a BitIconInfo, which is how a glyph from any other icon set is named. A set that names its glyphs with CSS classes - FontAwesome, Bootstrap Icons, and almost everything else - is described by a base class, a prefix and a name, and the factories put those together for you: Fa for FontAwesome (which fills in the fa- prefixes you leave out), Bi for Bootstrap Icons, Bit for the built-in set, and Css for the classes of any set at all, spelled out. A set that names its glyphs with a ligature written as the element's text - Material Icons and Material Symbols - is covered by Mi and Ms, which put the family on the class and the name inside the element. A ligature is the icon's own text, which a page translator would otherwise translate into a word that draws nothing, so an icon that renders one is marked as text not to translate. A plain string assigned to Icon is taken as the complete class list, which is the shortest way to write one out. Linking the set's own stylesheet is up to your app; the icon only names the glyph.

An app that draws all of its icons from one other set should not have to write that set out at every icon: IconResolver takes an IconName and answers with the icon it stands for, so a plain name goes on being a plain name. Give it to one icon, or cascade it to a whole subtree through BitParams. An Icon still wins over it, and a resolver that answers with nothing leaves the name to the built-in set - which is what lets one resolver cover the names it knows and fall through for the rest.

FontAwesome

Bootstrap Icons

Material Symbols

IconResolver (plain names, read as FontAwesome ones)

Size is one of the three icon sizes of the design system, so an icon scales with the preset rather than with a number written into the page. FontSize is for everything in between: any CSS length, or the inherit keyword, which makes the icon exactly as big as the text it sits in. It overrides Size when both are given.

Small

Medium

Large

FontSize

Sized by the text around it

Style and Class land on the icon element itself, which is the whole component - there is nothing inside it to reach - so anything CSS can do to a glyph is done from here. A rule of your own wins over the component's, because it is written later in the stylesheet.

Use BitIcon in right-to-left (RTL). A glyph is not mirrored by the direction alone - a checkmark, a clock and a bus look the same either way - so mirroring is opt-in through FlipRtl, which is what turns the glyphs that point somewhere and leaves the rest untouched. Dir sets the direction for one icon; a dir on any ancestor sets it for all of them, and FlipRtl follows either.