Utilities
Icon
Bit.BlazorUIGlyphSymbol
Icon draws one glyph: any of the 2,300 built-in Fabric MDL2 icons by name, a glyph of FontAwesome, Bootstrap Icons, Material Icons, Material Symbols or any CSS-class icon set, or an inline SVG of your own. It takes the theme's colors and sizes, comes plain, outlined, filled or circular, turns, mirrors and animates, and becomes a keyboard-operable button when you give it a click handler.
Notes
An icon is decorative by default and hidden from assistive technology. Give it an AriaLabel or a Title when it is the only thing carrying the meaning.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
IconName names a glyph of the built-in set (all of them are on the iconography page).
Disabled draws it in the disabled color.
Variant
Variant: Text (the default) is the bare glyph, Outline and Fill put it in a box of its own.
Circular turns that box into a circle of the same size for every glyph.
Rotate & Flip
Rotate turns the glyph by quarter turns, RotateAngle by any angle in degrees (and wins over Rotate),
Flip mirrors it on either axis or both. They combine, so one arrow covers every direction.
FlipRtl mirrors only in right-to-left: give it to glyphs that point somewhere, never to a clock or a checkmark.
FlipRtl, left-to-right and then inside a
dir="rtl" container:Animation
Animation loops the icon; a turn or a flip stays under it. AnimationDuration sets one cycle, AnimationDelay
the wait before the first (staggered, a wave), AnimationIterationCount stops an attention-seeking one after a few cycles.
Reduced motion slows every animation down; ForceAnimation restores its speed.
Spin
SpinReverse
Pulse
Beat
Fade
Shake
Bounce
BeatFade
Spin 4s
Spin 0.4s
Beat, turned 45
AnimationDelay
Fixed width
Font glyphs differ in width, so the labels beside them start at a different place on every row. FixedWidth gives every
icon the same box; the first list is without it, the second with it.
- Home
- Settings
- Profile
- Sign out
- Home
- Settings
- Profile
- Sign out
Clickable
OnClick makes the icon a button: a tab stop with a focus ring, hover and pressed states, Enter and Space, and a pointer
target grown to 24×24px without growing the icon. Name it with an AriaLabel or a Title; a toggle also takes an
aria-pressed. A disabled one leaves the tab order but keeps its Title tooltip. For anything more than an icon,
use a BitButton.
Refreshed 0 times.
Custom content
ChildContent replaces the glyph - an inline SVG, a sprite, an image - and keeps the icon's color, size and variant. Draw the
SVG with
fill="currentColor" and size it in em. An SVG sits on its bottom edge and rides high next to text;
Inline drops it onto the line.
Aligned by its box
and dropped onto the line with Inline
Accessibility
An unnamed icon is decorative:
aria-hidden, skipped by screen readers - right beside a label that says the same.
AriaLabel, Title (also a native tooltip) or your own aria-labelledby names it with the img role.
A native tooltip never shows for keyboard or touch users: for text meant to be read, give the icon a TabIndex and wrap it in a
BitTooltip. A focusable icon is never hidden and gets the themed focus ring - so
name it too: only a glyph with a name of its own (an IconName, a ligature) falls back to that name.
Ligature icons are marked translate="no"; forced-colors mode keeps variants and the disabled state visible.
Failed runs are retried three times, a minute apart.
Cascading parameters
BitParams hands a BitIconParams to every icon under it, so a toolbar or a status list sets its shared look once. It
is a default, not an override: the last icon keeps its own Variant.
Color
Color paints the icon in a theme role, so every preset and both schemes re-skin it. The semantic roles carry meaning; the
background, foreground and border roles are the neutral tiers of the surface. Like every component's colors, it is the default of
the --bit-Icon-* color variables, so one of those set around the icon wins over it.
Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
PrimaryBackground
SecondaryBackground
TertiaryBackground
PrimaryForeground
SecondaryForeground
TertiaryForeground
PrimaryBorder
SecondaryBorder
TertiaryBorder
External Icons
Icon takes a BitIconInfo for any other set: Fa (FontAwesome), Bi (Bootstrap Icons), Mi/Ms
(Material Icons/Symbols, ligature-based), Css for any class list, or a plain string. Link the set's stylesheet yourself.
IconResolver turns a plain IconName into another set's icon - once, or for a whole subtree through BitParams;
answering null leaves the name to the built-in set.
FontAwesome
Bootstrap Icons
Material Symbols
home
favorite
settings
rocket_launch
IconResolver (plain names read as FontAwesome ones; Accept falls through to the built-in set)
Size
Size picks one of the theme's three icon sizes, as the default of --bit-Icon-size, which wins over it. FontSize
takes any CSS length, or
inherit to match the surrounding text, and wins over both.
Sized by the text around it
Style & Class
Style and Class land on the icon element itself - the whole component. Style is also where the
--bit-Icon-* variables are set for one icon alone.
RTL
Use BitIcon in right-to-left (RTL). A glyph is not mirrored by the direction alone; FlipRtl opts in, and follows Dir
or any ancestor's
dir.
CSS variables
The public custom properties this component reads off its root, for what no parameter covers.
Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property:
set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it,
or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.
BitIcon CSS variables
| Name | Default value | Description |
|---|---|---|
| --bit-Icon-color | the main color of the icon's Color role | The icon's color: the glyph of a Text or an Outline icon, the box of a Fill one. It wins over the Color of the icon. currentColor makes a Text icon follow the text around it - set it around Text icons only, since a Fill icon would paint its box in its own glyph color. |
| --bit-Icon-contrast-color | the text color of the icon's Color role | The glyph drawn over the box of a Fill icon, and of a clickable Outline icon under the pointer. It wins over the Color of the icon. |
| --bit-Icon-hover-color | a shade of --bit-Icon-color when it is set, otherwise the hover color of the icon's Color role | The color of a clickable icon under the pointer. It wins over the Color of the icon. |
| --bit-Icon-active-color | a shade of the hover color when either variable above is set, otherwise the active color of the icon's Color role | The color of a clickable icon while pressed. It wins over the Color of the icon. |
| --bit-Icon-focus-color | the focus color of the icon's role | Color of the keyboard focus ring of a clickable or otherwise focusable icon. It wins over the Color of the icon. |
| --bit-Icon-size | per Size, --bit-siz-icon-sm/md/lg | Font size, which is the size of the glyph. It wins over the Size of the icon; FontSize wins over it. |
| --bit-Icon-padding | half a spacing unit (4px) | Room around the glyph in a Fill or an Outline box. |
| --bit-Icon-radius | --bit-shp-radius-control | Corner radius of a Fill or an Outline box. Circular wins over it. |
| --bit-Icon-border-width | --bit-shp-brd-width | Border width of a Fill or an Outline box. |
| --bit-Icon-fixed-width | 1.25em | Width of a FixedWidth icon, for a set whose widest glyph needs more (or less) room. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitIcon parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| Animation | BitIconAnimation? | null | A looping animation to play on the icon. It composes with Rotate, RotateAngle and Flip: a mirrored arrow still spins. |
| AnimationDuration | string? | null | How long one cycle of the animation takes, as any CSS time. Still slowed down under reduced motion. |
| AnimationDelay | string? | null | How long to wait before the animation starts, as any CSS time. |
| AnimationIterationCount | int? | null | How many times the animation plays before the icon comes to rest. Unset, it loops. Beat and Fade run out and back as two iterations. |
| ChildContent | RenderFragment? | null | Content rendered inside the icon element instead of a glyph - an inline svg, an image. The color, size and variant still apply. |
| Circular | bool | false | Draws the Fill or Outline box as a circle, the same size for narrow and wide glyphs. |
| Color | BitColor? | null | Specifies the color theme of the icon, BitColor.Primary when unset. It supplies the defaults of the --bit-Icon-* color variables, which win over it. |
| FixedWidth | bool | false | Renders the icon in a box of a fixed width so that a column of icons of different widths lines up. |
| Flip | BitIconFlip? | null | Mirrors the icon on the horizontal axis, the vertical axis, or both. |
| FlipRtl | bool | false | Mirrors the icon horizontally when it renders right-to-left, whether by its own Dir or an ancestor's dir. |
| FontSize | string? | null | Specifies the font size of the icon, as any CSS length or the inherit keyword. Overrides Size when both are given. |
| Icon | BitIconInfo? | null | Specifies the icon configuration for rendering icons from external icon libraries. Takes precedence over IconName when both name a glyph. |
| IconName | string? | null | The name of a glyph in the built-in Fabric MDL2 set (or in another set, through IconResolver). Ignored when Icon names a glyph. |
| IconResolver | Func<string, BitIconInfo?>? | null | Maps an IconName to an icon of another set - name => BitIconInfo.Fa(name), or a lookup of your own. Icon wins over it; answering null leaves the name to the built-in set. Cascades through BitParams. |
| Inline | bool | false | Drops an inline svg or image given as ChildContent onto the line of text it sits in. |
| OnClick | EventCallback<MouseEventArgs> | The callback for when the icon is clicked. The icon then becomes a button: a tab stop answering Enter and Space. Name it with an AriaLabel or a Title. | |
| Rotate | BitIconRotate? | null | Turns the icon by a quarter, a half, or three quarters of a turn. |
| RotateAngle | int? | null | Turns the icon by an angle of your own, in degrees, negative for counter-clockwise. It replaces Rotate when both are given, and composes with Flip and FlipRtl. |
| Size | BitSize? | null | Specifies the size of the icon, BitSize.Medium when unset. It supplies the default of --bit-Icon-size, which wins over it; FontSize wins over both. |
| Title | string? | null | The native tooltip text. It also names the icon for assistive technology. |
| Variant | BitVariant? | null | Specifies the visual styling variant of the icon. Default value is BitVariant.Text. |
BitIcon public members
| Name | Type | Default value | Description |
|---|---|---|---|
| FocusAsync | ValueTask | Gives focus to the icon element. Only an icon the browser can focus takes it: one with an OnClick handler, or one given a TabIndex of its own. | |
| FocusAsync(bool preventScroll) | ValueTask | Gives focus to the icon element, leaving the page scrolled where it is instead of bringing the icon into view. |
BitComponentBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabel | string? | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | string? | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | BitDir? | null | Gets or sets the text directionality for the component's content. |
| Disabled | bool | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| ForceAnimation | bool | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | Dictionary<string, object> | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. |
| Id | string? | null | Gets or sets the unique identifier for the component's root element. |
| Style | string? | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | string? | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | BitVisibility | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
BitComponentBase public members
| Name | Type | Default value | Description |
|---|---|---|---|
| UniqueId | Guid | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | ElementReference | Gets the reference to the root HTML element associated with this component. |
BitIconInfo properties
Names a glyph for any icon set. A class-based set (Fabric MDL2, FontAwesome, Bootstrap Icons) is described by BaseClass, Prefix and Name; a ligature-based set (Material Icons, Material Symbols) puts the family on BaseClass and the ligature on Content. The static factories build each of them: Bit(name), Fa(icons), Bi(name), Mi(name, style), Ms(name, style), Css(cssClasses), and From(icon, iconName) which resolves an Icon/IconName pair. A plain string converts implicitly and is taken as the complete class list.
| Name | Type | Default value | Description |
|---|---|---|---|
| Name | string? | null | The name of the icon. For an external set this can be the complete CSS class list when BaseClass and Prefix are empty. |
| BaseClass | string? | null | The base CSS class of the icon set - "bit-icon" for the built-in set, "bi" for Bootstrap Icons, "material-symbols-outlined" for Material Symbols. Leave it empty for a set that needs none. |
| Prefix | string? | null | The CSS class prefix written before the icon name - "bit-icon--" for the built-in set, "bi-" for Bootstrap Icons. Leave it empty for a set that uses none. |
| Content | string? | null | The text rendered inside the icon element - the ligature of a ligature-based icon set such as Material Icons or Material Symbols. Class-based sets leave it null. Only a component that renders the icon's content puts it on the page, which BitIcon does; the glyphs the library draws inside its other controls are class-based, so a ligature set has to be given to a BitIcon. |
| IsEmpty | bool | Whether this instance names no glyph at all - nothing to put in a class attribute, and nothing to write as the element's text. An empty instance is treated as no icon, so an IconName given beside it is still used. |
BitColor enum
| Name | Value | Description |
|---|---|---|
| Primary | 0 | Info Primary general color. |
| Secondary | 1 | Secondary general color. |
| Tertiary | 2 | Tertiary general color. |
| Info | 3 | Info general color. |
| Success | 4 | Success general color. |
| Warning | 5 | Warning general color. |
| SevereWarning | 6 | SevereWarning general color. |
| Error | 7 | Error general color. |
| PrimaryBackground | 8 | Primary background color. |
| SecondaryBackground | 9 | Secondary background color. |
| TertiaryBackground | 10 | Tertiary background color. |
| PrimaryForeground | 11 | Primary foreground color. |
| SecondaryForeground | 12 | Secondary foreground color. |
| TertiaryForeground | 13 | Tertiary foreground color. |
| PrimaryBorder | 14 | Primary border color. |
| SecondaryBorder | 15 | Secondary border color. |
| TertiaryBorder | 16 | Tertiary border color. |
BitSize enum
| Name | Value | Description |
|---|---|---|
| Small | 0 | Display icon using small size. |
| Medium | 1 | Display icon using medium size. |
| Large | 2 | Display icon using large size. |
BitVariant enum
| Name | Value | Description |
|---|---|---|
| Fill | 0 | Fill styled variant. |
| Outline | 1 | Outline styled variant. |
| Text | 2 | Text styled variant. |
BitIconRotate enum
| Name | Value | Description |
|---|---|---|
| Rotate90 | 0 | A quarter turn clockwise. |
| Rotate180 | 1 | A half turn. |
| Rotate270 | 2 | A quarter turn counter-clockwise. |
BitIconFlip enum
| Name | Value | Description |
|---|---|---|
| Horizontal | 0 | Mirrored left to right. |
| Vertical | 1 | Mirrored top to bottom. |
| Both | 2 | Mirrored on both axes, which is the same as a half turn for an asymmetric glyph. |
BitIconAnimation enum
| Name | Value | Description |
|---|---|---|
| Spin | 0 | Turns continuously clockwise - the loading spinner. |
| SpinReverse | 1 | Turns continuously counter-clockwise. |
| Pulse | 2 | Turns clockwise in eight discrete steps, the way a segmented spinner ticks around. |
| Beat | 3 | Scales up and back down, to draw the eye to something that just changed. |
| Fade | 4 | Fades out and back in. |
| Shake | 5 | Rocks back and forth, for something that needs attention now. |
| Bounce | 6 | Jumps up and lands again, squashing on the way out and on the way back - the heaviest of these. |
| BeatFade | 7 | Scales up and fades in together, which reads as a slower, softer Beat. |
BitVisibility enum
| Name | Value | Description |
|---|---|---|
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
BitDir enum
| Name | Value | Description |
|---|---|---|
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.