# Loading
## Description
Eighteen pure-CSS loading animations - spinners, dots, bars and shapes - sharing one API: color, size, stroke thickness, a label on any side, speed, pause, a delay that keeps quick work from flashing a loader, and a live region that announces the wait.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AriaLive | `string?` | null | The aria-live politeness of the root live region. Falls back to "polite" for the default status role and to the role's own politeness otherwise; ignored while the loader is decorative. |
| Classes | `BitLoadingClassStyles?` | null | Custom CSS classes for different parts of the loading component. |
| Color | `BitColor?` | null | The theme color of the drawing. An explicit value wins over --bit-Loading-color; left unset (and with no CustomColor), the loader is primary unless it says otherwise. |
| CustomColor | `string?` | null | Any CSS color for the drawing, currentColor included. Only applies while Color is unset. Like Color, it wins over --bit-Loading-color. |
| CustomSize | `int?` | null | The size of the drawing in px; the label scales along within a readable range. Only applies while Size is unset. Zero and negative values are ignored. Like Size, it wins over --bit-Loading-size and --bit-Loading-label-font-size. |
| Delay | `int` | 0 | How long, in ms, the loader waits before showing anything, so quick work never flashes it. Changing the value restarts the wait. |
| Inline | `bool` | false | Lays the loader out on the current line of text, a button or a table cell, at the size of the text (1em) unless Size or CustomSize is set. |
| Label | `string?` | null | The status text shown beside the drawing and announced by screen readers. |
| LabelPlacement | `BitPlacement?` | null | The side of the drawing the label sits on: Top by default, End for an Inline loader. Start and End follow the writing direction. |
| LabelTemplate | `RenderFragment?` | null | Custom content for the label. Takes the place of Label. |
| Paused | `bool` | false | Freezes the animation on its current frame, keeping the layout and the live region as they are. |
| Role | `string?` | null | The ARIA role of the root. Falls back to "status", a live region; "progressbar" makes an indeterminate progress bar named by AriaLabel, Label or "Loading"; "none" makes the loader decorative. |
| Size | `BitSize?` | null | The size of the loader: 40px, 64px or 88px, with the label on the matching step of the type ramp. An explicit value wins over --bit-Loading-size and --bit-Loading-label-font-size; left unset (and with no CustomSize), the loader is 64px - 1em when Inline - unless they say otherwise. |
| Speed | `double?` | null | A multiplier of the animation speed: 2 is twice as fast. Composes with reduced motion. Zero and negative values are ignored. An explicit value wins over --bit-Loading-speed; left unset, the loader runs at its normal speed unless it says otherwise. |
| Styles | `BitLoadingClassStyles?` | null | Custom CSS styles for different parts of the loading component. |
| Thickness | `int?` | null | The stroke width in px of the Ring, DualRing, Ripple, Xbox and Spinner loaders. Does not scale with the size. Zero and negative values are ignored. An explicit value wins over --bit-Loading-thickness; left unset, the stroke keeps its authored width unless it says otherwise. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| 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. |
### BitPlacement Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Top | 0 | The top edge. |
| Bottom | 1 | The bottom edge. |
| Start | 2 | The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top. |
| End | 3 | The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom. |
| Left | 4 | The left edge, in both reading directions. |
| Right | 5 | The right edge, in both reading directions. |
| Center | 6 | The middle of the axis, against neither edge. |
| TopAndBottom | 7 | Both edges of the block axis at once. |
| StartAndEnd | 8 | Both edges of the inline axis at once, following the reading direction the way Start and End do. |
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size, which renders a 40px loading component. |
| Medium | 1 | The medium size, which renders a 64px loading component. |
| Large | 2 | The large size, which renders an 88px loading component. |
### 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
### BitLoadingClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the BitLoading components. |
| Container | `string?` | null | Custom CSS classes/styles for the child container of the BitLoading components. |
| Child | `string?` | null | Custom CSS classes/styles for the child element(s) of the BitLoading components. |
| Label | `string?` | null | Custom CSS classes/styles for the label of the BitLoading components. |
| ScreenReaderText | `string?` | null | Custom CSS classes/styles for the visually hidden text a labelless BitLoading component announces to assistive technology. |
## 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-Loading-color` | --bit-clr-pri | Color of the drawing. The Color and CustomColor parameters win over it. |
| `--bit-Loading-track-color` | transparent | The full circle under the moving arcs of the Ring, DualRing and Xbox loaders. |
| `--bit-Loading-size` | 64px (1em when Inline) | Width and height of the drawing, which is laid out from it. Any CSS length, em and rem included. The Size and CustomSize parameters win over it. |
| `--bit-Loading-thickness` | The width each drawing was made with | Stroke width of the Ring, DualRing, Ripple, Xbox and Spinner loaders. The Thickness parameter wins over it. |
| `--bit-Loading-speed` | 1 | Multiplier of the animation speed; a positive number. The Speed parameter wins over it. |
| `--bit-Loading-gap` | spacing(1) | Room between the drawing and the label. |
| `--bit-Loading-label-color` | The surrounding text color | Color of the label. |
| `--bit-Loading-label-font-size` | --bit-tpg-fs-sm (1em when Inline) | Text size of the label. The Size and CustomSize parameters win over it. |
| `--bit-Loading-label-font-weight` | $tg-fw-regular | Text weight of the label. |
## Examples
\n**Basic**:
```razor
Restoring your session
```
\n**Speed & Paused**:
```razor
Run a 1.5s task
@if (isWorking)
{
Syncing
```
\n**Overlay**:
```razor
Refresh orders
@* Only the stale content is busy: a busy region holds back its announcements, the loader's included. *@
```
```csharp
private bool isRefreshing;
private async Task Refresh()
{
isRefreshing = true;
await Task.Delay(2000);
isRefreshing = false;
}
```
\n**Accessibility**:
```razor
@* role="status" aria-live="polite" and a visually hidden "Loading" by default. *@
```
```csharp
private readonly BitLoadingParams[] loadingParams =
[
new()
{
Thickness = 3,
Speed = 1.5,
LabelPlacement = BitPlacement.End
}
];
```
\n**Color**:
```razor
Fetching the latest results
Order #1024 - Shipped
Order #1025 - Processing
Order #1026 - Delivered