Skip to content
BlazorUI

Documentation

Iconography

2313 icons Fabric MDL2 Bit.BlazorUI.Icons

bit BlazorUI draws its icons from Microsoft's Fabric (MDL2) set, shipped as a font rather than as thousands of SVG files. A glyph is a character: it scales with font-size, takes currentColor, costs one request for the whole set and nothing per icon after that. Every component that shows an icon names one from this page.

Browse the icons

Search by name or by what another set calls the same thing, narrow by category, and open any icon for every string you might need to paste.

2313 icons in the Fabric (MDL2) set, 25 of them without the icons package

Install the icon pack

The icons ship separately from the components, so an app that does not use them does not download them.

Add the Bit.BlazorUI.Icons package and link its stylesheet — both halves, or the glyphs come out as empty boxes. It is one of the optional steps of the getting started page. 

dotnet add package Bit.BlazorUI.Icons
<link href="_content/Bit.BlazorUI.Icons/styles/bit.blazorui.icons.css" rel="stylesheet" />

The core package embeds a 25-glyph subset of the same font — about 3 KB — because its own components draw with it. These render in an app that never installed anything above, which is why a date picker has arrows and a message has a dismiss cross before the icon pack is anywhere in the project:

Anything else — every other name on this page — needs the package.

Use an icon

Three ways in, depending on whether the icon is the whole component, a part of one, or markup of your own.

The BitIcon component

BitIcon renders one glyph. IconName takes a name from BitIconName, which is a class of string constants — so the compiler catches a typo that a raw string would not. 

<BitIcon IconName="@BitIconName.Rocket" />
<BitIcon IconName="@BitIconName.CalendarWeek" />
<BitIcon IconName="@BitIconName.Shield" />
<BitIcon IconName="@BitIconName.Lightbulb" />

The full parameter list — and every state of it — is on the BitIcon page.

On another component

Anything in the library that can show an icon takes the same name. The parameter is IconName on the component itself, or a property of the same name on the item type of a list-shaped one — a nav item, a menu item, a pivot header.

Draft
Saved
<BitButton IconName="@BitIconName.Save">Save</BitButton>
<BitButton IconOnly AriaLabel="Delete" IconName="@BitIconName.Delete" />
<BitTag IconName="@BitIconName.Tag" Text="Draft" />
<BitMessage IconName="@BitIconName.CheckMark" Color="BitColor.Success">Saved</BitMessage>

From your own markup

The stylesheet is the whole API: a glyph is a ::before on a class, so any element can carry one without a component around it. This is also what the browser above renders — two thousand components would cost more than two thousand glyphs are worth. 

<i aria-hidden="true" class="bit-icon bit-icon--Rocket"></i>

Every icon's panel carries that class ready to paste, and the code point behind it for CSS that draws the glyph itself: 

.my-button::before {
    content: "\F3B3"; /* Rocket */
    font-family: "Fabric MDL2";
}

Size, color and variant

An icon is text, so it inherits everything text does - and takes the same three scales every other component in the library takes.

Size maps to the library's icon ramp, Color to its semantic roles, and Variant decides whether the glyph is drawn bare, in a ring, or on a filled chip. All three read from the theme, so an icon re-skins with the rest of the page when a preset changes.

Size

Small Medium Large font-size

Variant

Text Outline Fill

Color

Primary Secondary Tertiary Info Success Warning Error

Nothing stops the glyph being sized and colored as the text it is. Anywhere the three steps are not the right answer, set font-size and color yourself and the icon follows: 

<BitIcon IconName="@BitIconName.Rocket" Style="font-size: 2.5rem; color: tomato;" />

Use another icon set

Font Awesome, Bootstrap Icons, or anything else that renders a glyph from a CSS class - on the same components, through one parameter.

Every component with an IconName also has an Icon parameter that takes a BitIconInfo. It carries CSS classes rather than a Fabric name, which is all any class-based icon library needs. Icon wins when both are set.

Three helpers cover the common sets, and Css covers the rest by passing the classes through untouched: 

BitIconInfo.Fa("fa-solid fa-house")   // Font Awesome - the "fa-" prefix is added if missing
BitIconInfo.Bi("house")               // Bootstrap Icons - renders "bi bi-house"
BitIconInfo.Css("my-icon my-house")   // anything else - the classes, verbatim
BitIconInfo.Bit("Home")               // back to the built-in set
Font Awesome
<BitIcon Icon="@BitIconInfo.Fa("solid house")" />
<BitIcon Icon="@BitIconInfo.Fa("brands github")" />
<BitButton Icon="@BitIconInfo.Fa("solid rocket")">Launch</BitButton>
<BitTag Icon="@BitIconInfo.Fa("solid heart")" Text="Font Awesome" />

The set's own stylesheet has to be referenced by the app — the library never fetches one for you. Nothing else changes: sizing, coloring and disabled states are the component's, not the icon set's.

Accessibility

An icon is either decoration or information, and the two are marked up differently. Deciding which is the whole job.

Decorative — the icon repeats a label that is already there, and must add nothing to what is announced. The library's components draw the glyph as an empty element with no text of its own, so a BitButton with a word beside its icon announces the word and nothing else. In markup you write yourself, mark the glyph aria-hidden="true".

Informative — the icon is the only thing saying what the control does. It needs a text alternative, which on BitIcon and on every icon-only control is AriaLabel. An icon-only button without one is a button screen readers announce as nothing at all. 

@* Decorative: the word "Save" is the label *@
<BitButton IconName="@BitIconName.Save">Save</BitButton>

@* Informative: the glyph is the label, so it needs one *@
<BitButton IconOnly AriaLabel="Save" Title="Save" IconName="@BitIconName.Save" />
<BitIcon IconName="@BitIconName.Warning" AriaLabel="Warning" />
  • Never let color carry the meaning on its own. A red glyph and a green glyph are the same glyph to a reader who cannot tell them apart — pair the color with a shape that differs, or with a word.
  • Give an icon-only control a real target. The glyph is 16 px; the button around it should be at least 24 px, and 44 px where a finger is expected. The library's own sizes already are.
  • Add Title as well as AriaLabel on an icon-only control. The label serves a screen reader; the tooltip serves everyone who simply does not recognise the glyph.

Guidelines

What separates an interface that uses icons from one that is decorated with them.

Do

  • Stay inside one set. Fabric next to Font Awesome reads as two designs sharing a screen.
  • Use the same icon for the same action everywhere — one delete glyph, not three.
  • Let the icon sit beside a label wherever there is room for one.
  • Size the glyph to the text it sits with, and let it take currentColor.
  • Prefer the plainest glyph that says it. MDL2 offers a dozen mails; the one called Mail is almost always right.

Don't

  • Don't use an icon for a concept it does not already carry. If it needs explaining, use a word.
  • Don't rotate or mirror a glyph to mean something else — the set has a name for that direction.
  • Don't put an icon on every row of a list. When everything is emphasised, nothing is.
  • Don't scale a glyph past about 32 px as an illustration; it is a UI icon and its strokes thin out.
  • Don't ship the whole icon pack for the handful of glyphs a marketing page uses — the core subset may already have them.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.