Skip to content
BlazorUI

Buttons

ToggleButton

Bit.BlazorUI

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.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Left on its own, the BitToggleButton owns its state: every click flips it and the checked styling follows along, with no binding and no event handler involved.

Variant

The variant sets how much visual weight the BitToggleButton carries: Fill (the default) for a solid button, Outline for a bordered one, and Text for a borderless one. Whichever you pick, the checked state renders in a darker shade of the same color, so the two states stay apart in all three.



Disabled:



A disabled BitToggleButton stays focusable by default so screen reader users can still find it, rendering aria-disabled instead of the native disabled attribute. Set AllowDisabledFocus to false to take it out of the tab order instead.

Texts & Titles

Text labels both states the same way, leaving the color to carry the state. OnText and OffText label each state separately, which reads well when the wording is the clearest signal of what is going on - though it also changes the accessible name, so the BitToggleButton stops announcing aria-pressed. The Accessibility section covers why, and what to do about it.

Text:





On/Off Texts:





Title follows the same shape and fills the native tooltip, with OnTitle and OffTitle overriding it per state. It is the natural companion to IconOnly, where the button has no visible wording of its own - though a tooltip never reaches keyboard or touch users, so it supplements an AriaLabel rather than replacing one. Hover the two below:

Icons

Icons follow the same shape as the text: IconName for both states, OnIconName and OffIconName for one each. IconPosition moves the icon after the content, and IconOnly drops the text and squares up the padding for a compact, toolbar-style button - which leaves nothing behind to name it, so give an icon-only BitToggleButton an AriaLabel.

IconName:





On/Off IconNames:





IconPosition:




No text:




IconOnly:

Checked appearance

The darker checked shade is enough for most cases, but some toggles mean genuinely different things in their two states and should look the part. OnColor/OffColor and OnVariant/OffVariant let the whole appearance change with the state, each falling back to the general Color and Variant when it is not set, so you only override the axis you care about.

OnColor & OffColor:




OnVariant & OffVariant:




Both, on top of a shared Color:

CheckMark

A checked state told only by a shade of color is invisible to anyone who cannot perceive that shade, and disappears outright in Windows High Contrast. ShowCheckMark adds a check mark in the checked state so the state carries a shape as well as a color, which is what makes a row of toggle buttons readable at a glance. FixedCheckMark reserves the mark's space while unchecked so the content does not jump on every click, and CheckMarkIconName swaps the mark for any other icon.

ShowCheckMark:




FixedCheckMark:




CheckMarkIconName:

Binding

Who owns the checked state is up to you. DefaultIsChecked seeds it once and leaves the BitToggleButton in charge, @bind-IsChecked keeps it in sync with a field you control, and OnChange just reports it. The ToggleAsync and FocusAsync methods drive it from code, the former taking the same path a click does.

DefaultIsChecked:





Two-way bound:







OnChange:



Check status: False




ToggleAsync & FocusAsync:

Templates

When the icon and the text are not enough, ChildContent replaces the whole body of the BitToggleButton for both states. OnTemplate and OffTemplate do the same one state at a time, so the two states can differ in structure and not just in wording.

ChildContent:





OnTemplate & OffTemplate:

Events

Three callbacks fire in a fixed order around a click: OnClick first, while the state is still the old one; then OnChanging, carrying the state the BitToggleButton is about to move to; and finally OnChange, once the new state is committed.

OnClick:





OnChanging is the veto point: setting Cancel on its arguments leaves the BitToggleButton where it was, so a toggle can be refused instead of silently reverted afterwards. It is awaited, so it can take its time - asking for confirmation, or checking with the server before letting the state through.




Cancelled attempts: 0




A BitToggleButton inside a clickable container fires that container's handler too, which is rarely what you want when the toggle sits in a selectable card or a list row. StopPropagation keeps the click to itself. Both toggles below sit in the same clickable box:


Container clicks: 0

Loading

A toggle that has to reach a server is not really toggled until the server says so, and clicking it three more times in the meantime helps nobody. IsLoading covers the content with a spinner and blocks further clicks for exactly that window; Reclickable lifts the block if the extra clicks are harmless.




Both of these are loading, but only the second one still reacts. Click each of them:




AutoLoading does the bookkeeping for you: the BitToggleButton stays loading for as long as the OnClick and OnChange callbacks take, so an async toggle needs no loading flag of its own.




LoadingLabel puts a word next to the spinner, and LoadingLabelPosition places it on any of the four sides:




LoadingTemplate replaces the spinner and the label altogether:

FullWidth

A BitToggleButton is inline by default and only as wide as its content. FullWidth stretches it across its container instead, which is what you want when it sits alone in a narrow column, a form, or a settings row, and its edges should line up with everything around it.

FixedColor

The foreground color normally shifts on hover and focus to reinforce that something is happening. With the background colors that is counterproductive - the hover shade is close enough to the content that the text and the icon wash out. FixedColor pins the foreground so it stays legible throughout.

Accessibility

A toggle button announces its state through aria-pressed. That only works while the accessible name stays the same in both states: a name that changes together with the state leaves screen reader users unable to tell what was announced. So by default the BitToggleButton drops aria-pressed as soon as it detects that the name differs between the two states.

The examples below differ in their markup rather than in their looks, so open the browser's element inspector to see what each one actually renders.

Here OnText and OffText differ, so the name carries the state and no aria-pressed is rendered:




Adding a stable AriaLabel pins the name down for both states, so aria-pressed comes back:




AriaMode takes the decision back from the automatic one. Pressed always renders aria-pressed, Switch renders role="switch" with aria-checked instead - which reads better for an on/off setting than a pressed/not pressed one - and None renders no state attribute at all, for a button like play/pause whose own content already says which state it is in:




An icon-only BitToggleButton has no visible wording at all, so its AriaLabel is its whole name. OnAriaLabel and OffAriaLabel let that name change with the state - useful when the name is better phrased as the action the click performs than as the state it is in. Being a changing name, it drops aria-pressed for the same reason the changing text does:




When a visible element already labels the toggle button, AriaLabelledBy points at it instead of repeating the wording in an AriaLabel that could drift out of sync with it:

Wi-Fi



AriaDescription adds a visually hidden description, and AriaControls points at the element the toggle button controls:

Expands the details panel below the button.

The details panel is hidden.

Color

The whole general color set is available, Primary being the default. Each color also supplies the darker shade used for the checked state, so a checked and an unchecked BitToggleButton read as one control in two states rather than as two unrelated buttons. Click through the ones below to see both.




















Disabled:


















External Icons

The built-in icon set is not a requirement. Icon, OnIcon and OffIcon take a BitIconInfo that renders whatever CSS classes you give it, so any icon font works - BitIconInfo.Fa for FontAwesome, BitIconInfo.Bi for Bootstrap Icons, or BitIconInfo.Css for anything else. Just remember to reference the library's stylesheet yourself.










CheckMarkIcon takes the same kind of value:

Size

Three preset sizes scale the typography, the padding and the icon together, so a BitToggleButton keeps its proportions at any of them. Icon-only ones get square padding at each size, which is what keeps a toolbar row of them evenly spaced.


Small:







Medium:







Large:




Style & Class

Style and Class reach the root element, while Styles and Classes address the individual parts - the root, the icon, the text, the check mark and the loading pieces. Both of them also carry a Checked entry, which is layered on top of the rest whenever the BitToggleButton is checked, so a state-specific override does not need a conditional in your markup.

Component's Style & Class:



Styles & Classes:



The check mark and the loading parts are addressable in the same way:

RTL

Setting Dir to Rtl mirrors the BitToggleButton: the icon moves to the right of the text and the spacing follows it, since the layout is built from logical properties rather than fixed left and right ones. The same happens automatically when an ancestor cascades the direction down.

API

Every parameter, public member, sub-class and enum this component exposes.

BitToggleButton 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.

BitToggleButton 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.

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.
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.

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.

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.

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.

Feedback

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