# Icon
**Also known as:** Glyph, Symbol
## Description
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.
## 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. An explicit value wins over the --bit-Icon-* color variables; left unset, the icon is primary unless they say otherwise. |
| 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. An explicit value wins over --bit-Icon-size; left unset, the icon is medium unless it says otherwise. 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. |
| 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. An attribute written on the component wins over an entry of the same name. |
| 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. |
## 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. |
| 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. |
## Enums
### BitColor Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Primary | 0 | 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 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The 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. |
## Sub Classes
### 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. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-Icon-color` | --bit-clr-pri | The icon's color: the glyph of a Text or an Outline icon, the box of a Fill one. The Color parameter wins over it. 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` | --bit-clr-pri-text | The glyph drawn over the box of a Fill icon, and of a clickable Outline icon under the pointer. The Color parameter wins over it. |
| `--bit-Icon-hover-color` | a shade of --bit-Icon-color when it is set, otherwise --bit-clr-pri-hover | The color of a clickable icon under the pointer. The Color parameter wins over it. |
| `--bit-Icon-active-color` | a shade of the hover color when either variable above is set, otherwise --bit-clr-pri-active | The color of a clickable icon while pressed. The Color parameter wins over it. |
| `--bit-Icon-focus-color` | --bit-clr-pri-focus | Color of the keyboard focus ring of a clickable or otherwise focusable icon. The Color parameter wins over it. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too. |
| `--bit-Icon-size` | --bit-siz-icon-md | Font size, which is the size of the glyph. The Size parameter wins over it, and FontSize over both. |
| `--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. |
## Examples
\n**Basic**:
```razor
Shake 3 times (replay)
```
```csharp
private readonly BitIconParams[] iconParams =
[
new()
{
Variant = BitVariant.Outline,
Circular = true,
}
];
```
\n**Color**:
```razor
@foreach (var color in colors)
{
();
// The background roles are the page's own surface colors, so they are shown on a dark panel to be seen at all.
private static bool IsBackground(BitColor color) =>
color is BitColor.PrimaryBackground or BitColor.SecondaryBackground or BitColor.TertiaryBackground;
```
\n**External Icons**:
```razor
faResolver =
name => name is "house" or "heart" or "rocket" ? BitIconInfo.Fa($"solid {name}") : null;
// The same resolver given to every icon of a subtree at once:
// ...
```
\n**Size**:
```razor
Home Settings Profile Sign out
Home Settings Profile Sign out
Refreshed @clickCount times.
```
```csharp
private bool isStarred = true;
private int clickCount;
```
\n**Custom content**:
```razor
Aligned by its box
and dropped onto the line with Inline
```
\n**Accessibility**:
```razor
Sized by the text around it
```
\n**Style & Class**:
```razor