Accent color
# ToggleButton
## Description
ToggleButton is a button that stays pressed. Instead of firing an action and forgetting it, it holds an on/off state and shows which one it is currently in. It suits the kind of setting that belongs right next to the thing it affects - muting a microphone, bolding a selection, pinning an item - where a toolbar button reads better than a checkbox or a switch. Its text, icon, color and variant can all differ between the two states, it can stay in a loading state while an async toggle is being saved, and it exposes its state to screen readers through aria-pressed.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| AllowDisabledFocus | `bool` | true | Keeps the disabled toggle button focusable and discoverable by screen readers, rendering aria-disabled instead of the native disabled attribute. Set it to false to render the native disabled attribute and remove the toggle button from the tab order. |
| AriaControls | `string?` | null | The id of the element that the toggle button controls (rendered into aria-controls). |
| AriaDescription | `string?` | null | Detailed description of the toggle button for the benefit of screen readers (rendered into aria-describedby). |
| AriaHidden | `bool` | false | If true, adds an aria-hidden attribute instructing screen readers to ignore the toggle button. |
| AriaLabelledBy | `string?` | null | The id of the element that labels the toggle button (rendered into aria-labelledby). |
| AriaMode | `BitToggleButtonAriaMode?` | null | Determines which ARIA state attribute the toggle button exposes to assistive technologies. The default Auto mode drops aria-pressed when the accessible name of the toggle button changes between the two states. |
| AutoFocus | `bool` | false | If true, the toggle button automatically receives focus when the page renders. |
| AutoLoading | `bool` | false | If true, enters the loading state automatically while awaiting the click and change events, preventing subsequent clicks by default. |
| CheckMarkIcon | `BitIconInfo?` | null | The check mark icon to display using custom CSS classes for external icon libraries. Takes precedence over CheckMarkIconName when both are set. |
| CheckMarkIconName | `string?` | null | The name of the check mark icon that renders in the checked state when ShowCheckMark is enabled. |
| ChildContent | `RenderFragment?` | null | The content of the toggle button. |
| Classes | `BitToggleButtonClassStyles?` | null | Custom CSS classes for different parts of the toggle button. |
| Color | `BitColor?` | null | The general color of the toggle button. |
| DefaultIsChecked | `bool?` | null | Default value of the IsChecked parameter. |
| FixedCheckMark | `bool` | false | Keeps the space of the check mark reserved in the unchecked state so the content does not shift while toggling. |
| FixedColor | `bool` | false | Preserves the foreground color of the toggle button through hover and focus. |
| FullWidth | `bool` | false | Expands the toggle button width to 100% of the available width. |
| Icon | `BitIconInfo?` | null | The icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. |
| IconName | `string?` | null | The icon name from built-in Fluent UI icons that renders inside the toggle button. |
| IconOnly | `bool` | false | Determines that only the icon should be rendered and changes the styles accordingly. |
| IconPosition | `BitIconPosition?` | null | The position of the icon relative to the content of the toggle button. |
| IsChecked | `bool` | false | Determines if the toggle button is in the checked state. |
| IsLoading | `bool` | false | Determines whether the toggle button is in the loading state, which replaces its content with a spinner and prevents subsequent clicks unless Reclickable is enabled. |
| LoadingLabel | `string?` | null | The loading label text to show next to the spinner icon. |
| LoadingLabelPosition | `BitLabelPosition` | BitLabelPosition.End | The position of the loading label in regards to the spinner icon. |
| LoadingTemplate | `RenderFragment?` | null | The custom template used to replace the default content of the toggle button in the loading state. |
| OffAriaLabel | `string?` | null | The aria-label of the toggle button when it is not checked. |
| OffColor | `BitColor?` | null | The color of the toggle button when it is not checked. Falls back to the Color parameter when not provided. |
| OffIcon | `BitIconInfo?` | null | The icon to display when the toggle button is not checked, using custom CSS classes for external icon libraries. Takes precedence over OffIconName. |
| OffIconName | `string?` | null | The icon from built-in Fluent UI icons when the toggle button is not checked. |
| OffTemplate | `RenderFragment?` | null | The custom content of the toggle button when it is not checked. |
| OffText | `string?` | null | The text of the toggle button when it is not checked. |
| OffTitle | `string?` | null | The title of the toggle button when it is not checked. |
| OffVariant | `BitVariant?` | null | The visual variant of the toggle button when it is not checked. Falls back to the Variant parameter when not provided. |
| OnAriaLabel | `string?` | null | The aria-label of the toggle button when it is checked. |
| OnChange | `EventCallback<bool>` | | Callback for when the IsChecked value has changed. |
| OnChanging | `EventCallback<BitToggleButtonChangeArgs>` | | Callback invoked before the checked state changes, letting the change be cancelled by setting Cancel on its arguments. |
| OnClick | `EventCallback<MouseEventArgs>` | | Callback for when the toggle button is clicked. |
| OnColor | `BitColor?` | null | The color of the toggle button when it is checked. Falls back to the Color parameter when not provided. |
| OnIcon | `BitIconInfo?` | null | The icon to display when the toggle button is checked, using custom CSS classes for external icon libraries. Takes precedence over OnIconName. |
| OnIconName | `string?` | null | The icon from built-in Fluent UI icons when the toggle button is checked. |
| OnTemplate | `RenderFragment?` | null | The custom content of the toggle button when it is checked. |
| OnText | `string?` | null | The text of the toggle button when it is checked. |
| OnTitle | `string?` | null | The title of the toggle button when it is checked. |
| OnVariant | `BitVariant?` | null | The visual variant of the toggle button when it is checked. Falls back to the Variant parameter when not provided. |
| Reclickable | `bool` | false | Enables re-clicking while the toggle button is in the loading state. |
| ShowCheckMark | `bool` | false | Renders a check mark in the checked state so the state is not conveyed by color alone. |
| Size | `BitSize?` | null | The size of the toggle button. |
| StopPropagation | `bool` | false | If true, stops the click event from bubbling up to the parent elements. |
| Styles | `BitToggleButtonClassStyles?` | null | Custom CSS styles for different parts of the toggle button. |
| Text | `string?` | null | The text of the toggle button. |
| Title | `string?` | null | The title to show when the mouse is placed on the toggle button. |
| Variant | `BitVariant?` | null | The visual variant of the toggle button. |
| 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. |
| 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. |
| IsEnabled | `bool` | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. |
| 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 root element of the toggle button. |
| ToggleAsync | `Task` | | Toggles the checked state of the toggle button, going through the same cancellation and change notification path a click does. |
| 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
### BitToggleButtonAriaMode Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Auto | 0 | Renders aria-pressed, unless the accessible name of the toggle button changes between the checked and unchecked states, in which case no state attribute is rendered. |
| Pressed | 1 | Always renders aria-pressed, even when the accessible name changes between the two states. |
| Switch | 2 | Renders role="switch" along with aria-checked instead of aria-pressed. |
| None | 3 | Renders no state attribute at all, for content that already conveys the state. |
### 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. |
### BitIconPosition Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Start | 0 | Icon renders before the content (default). |
| End | 1 | Icon renders after the content. |
### BitLabelPosition Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Top | 0 | The label renders above the spinner. |
| End | 1 | The label renders after the spinner. |
| Bottom | 2 | The label renders below the spinner. |
| Start | 3 | The label renders before the spinner. |
### BitSize Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Small | 0 | The small size button. |
| Medium | 1 | The medium size button. |
| Large | 2 | The large size button. |
### BitVariant Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Fill | 0 | Fill styled variant. |
| Outline | 1 | Outline styled variant. |
| Text | 2 | Text styled variant. |
### 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
### BitToggleButtonClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the BitToggleButton. |
| CheckMark | `string?` | null | Custom CSS classes/styles for the check mark element of the BitToggleButton. |
| Checked | `string?` | null | Custom CSS classes/styles for the checked state of the BitToggleButton. |
| HiddenContent | `string?` | null | Custom CSS classes/styles for the container of the hidden content of the BitToggleButton in the loading state. |
| Icon | `string?` | null | Custom CSS classes/styles for the icon element of the BitToggleButton. |
| LoadingContainer | `string?` | null | Custom CSS classes/styles for the loading container of the BitToggleButton. |
| LoadingLabel | `string?` | null | Custom CSS classes/styles for the loading label of the BitToggleButton. |
| Spinner | `string?` | null | Custom CSS classes/styles for the loading spinner of the BitToggleButton. |
| Text | `string?` | null | Custom CSS classes/styles for the text element of the BitToggleButton. |
### BitToggleButtonChangeArgs Properties
The arguments of the OnChanging callback of the BitToggleButton.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Value | `bool` | false | The checked state the toggle button is about to move to. |
| Cancel | `bool` | false | Set to true to cancel the change and keep the current checked state. |
## Examples
\n**Basic**:
```razor
Microphone
```
\n**Variant**:
```razor
Fill
Outline
Text
Fill
Outline
Text
Not focusable
```
\n**Texts & Titles**:
```razor
Toggle it
Focus it
```
```csharp
private bool twoWayBoundValue;
private bool onChangeValue;
private BitToggleButton programmaticToggleRef = default!;
private async Task FocusTheToggleButton() => await programmaticToggleRef.FocusAsync();
```
\n**Templates**:
```razor
```
\n**Events**:
```razor
Click me (@clickCounter)
```
```csharp
private bool isLoading;
private int reclickCounter;
private int blockedClickCounter;
private async Task HandleAutoLoadingChange()
{
// stands in for persisting the new state somewhere slow
await Task.Delay(2000);
}
```
\n**FullWidth**:
```razor
Primary
Primary
Primary
Secondary
Secondary
Secondary
Tertiary
Tertiary
Tertiary
Info
Info
Info
Success
Success
Success
Warning
Warning
Warning
SevereWarning
SevereWarning
SevereWarning
Error
Error
Error
PrimaryBackground
PrimaryBackground
PrimaryBackground
SecondaryBackground
SecondaryBackground
SecondaryBackground
TertiaryBackground
TertiaryBackground
TertiaryBackground
PrimaryForeground
PrimaryForeground
PrimaryForeground
SecondaryForeground
SecondaryForeground
SecondaryForeground
TertiaryForeground
TertiaryForeground
TertiaryForeground
PrimaryBorder
PrimaryBorder
PrimaryBorder
SecondaryBorder
SecondaryBorder
SecondaryBorder
TertiaryBorder
TertiaryBorder
TertiaryBorder
Primary
Primary
Primary
Secondary
Secondary
Secondary
Tertiary
Tertiary
Tertiary
Info
Info
Info
Success
Success
Success
Warning
Warning
Warning
SevereWarning
SevereWarning
SevereWarning
Error
Error
Error
PrimaryBackground
PrimaryBackground
PrimaryBackground
SecondaryBackground
SecondaryBackground
SecondaryBackground
TertiaryBackground
TertiaryBackground
TertiaryBackground
PrimaryForeground
PrimaryForeground
PrimaryForeground
SecondaryForeground
SecondaryForeground
SecondaryForeground
TertiaryForeground
TertiaryForeground
TertiaryForeground
PrimaryBorder
PrimaryBorder
PrimaryBorder
SecondaryBorder
SecondaryBorder
SecondaryBorder
TertiaryBorder
TertiaryBorder
TertiaryBorder
```
\n**External Icons**:
```razor
Check status: @onChangeValue
Cancelled attempts: @cancelledCounter
Container clicks: @containerClickCounter
```
```csharp
private int clickCounter;
private bool allowChange;
private int cancelledCounter;
private int containerClickCounter;
private void HandleOnChanging(BitToggleButtonChangeArgs args)
{
if (allowChange) return;
args.Cancel = true;
cancelledCounter++;
}
```
\n**Loading**:
```razor
@(detailsVisible ? "The details panel is visible." : "The details panel is hidden.")
```
\n**Color**:
```razor