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, or through whichever semantics its AriaMode selects - aria-checked on a role of its own, aria-expanded for a disclosure, or none at all.
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. It also keeps its
tooltip, which is where a Title can say why it is off. Set AllowDisabledFocus to false
to render the native attribute and take it out of the tab order instead - at the cost of both.
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. With nothing else to go on a screen reader falls back to the
tooltip, which is why both of these carry an AriaLabel: a title that changed with the state would
take the accessible name with it. Hover the two below:
Icons
Icons follow the same shape as the text: IconName for both states, OnIconName and
OffIconName for one each. IconPlacement moves the icon after the content, and IconOnly
drops the text and squares up the padding for a compact, toolbar-style button - the wording is not thrown
away with it, since the Text of a button that renders none becomes its accessible name.
IconName:
On/Off IconNames:
IconPlacement:
A BitToggleButton with no text squares up either way - because none was supplied, or because
IconOnly drops the one that was. The first two below have nothing left to name them, which is what
their AriaLabel is for; the third is announced by the Text it does not render, and the last
pins a stable name over a pair of per-state texts:
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:
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. Every pair below is the same markup twice, seeded to a different state.
OnColor & OffColor:
OnVariant & OffVariant:
Both, on top of a shared Color:
Disabling a BitToggleButton does not take its state with it: a setting greyed out at on and one
greyed out at off are different facts, so the checked one keeps its own colors and is dimmed
rather than repainted in the disabled ones.
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 - the same button twice, seeded to a different state: the checked one is wider than the
unchecked one by exactly the mark.
FixedCheckMark - the same two, now the same width:
CheckMarkIconName:
Templates
When the icon and the text are not enough, ChildContent replaces the whole body of the
BitToggleButton for both states - the icon and the check mark included, since they are part of the body it
stands in for. OnTemplate and OffTemplate do the same one state at a time, so the two states
can differ in structure and not just in wording. Two templates that read differently also change the
accessible name, which the automatic AriaMode cannot detect the way it detects a changing text, so
give a two-template BitToggleButton an AriaLabel to pin its name down.
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. A blocked BitToggleButton stops responding to the pointer with
it - no hover shade, no pressed shade, no pointer cursor - and renders aria-disabled beside
aria-busy, which says that something is happening rather than that pressing it now does nothing.
Reclickable lifts the block, and all of that with it, where 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.
Most toggles come back fast enough that a spinner only flashes. LoadingDelay holds it back for that
long, while the click guard still applies from the first click. Both toggles below take two seconds; only
the second one waits 700ms before admitting it.
LoadingLabel puts a word next to the spinner, and LoadingLabelPlacement places it on any of
the four sides. It is also announced to screen readers when the loading starts - the spinner itself says
nothing - while the content stays in place behind it, so the BitToggleButton keeps its name while it is busy.
Saving...
Saving...
Saving...
Saving...
On an IconOnly BitToggleButton the label is announced but not shown, so the square keeps its shape
while it loads:
Saving...
LoadingTemplate replaces the spinner and the label altogether:
FullWidth & NoWrap
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.
Once the container decides the width, a long label wraps onto a second line and makes the button taller
than the ones around it. NoWrap keeps it on one line and ends it with an ellipsis instead - so pair
it with a Title, which is the only thing left showing the full wording.
FixedColor
The Outline and Text variants draw their content in the color itself and swap it for the one that
reads against the fill as soon as a fill appears on hover. With a background color the first of those
is roughly the page behind it, so the content barely shows at rest. FixedColor pins the
readable one down instead - in both states, and through hover and press.
Without, then with - hover each of them:
The same on the Text variant, which has no border left to make it out by either:
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:
The name is whatever a screen reader would actually read, not just the text: with nothing else to go on
it falls back to the tooltip, so a per-state OnTitle/OffTitle on an icon-only
BitToggleButton drops aria-pressed too - unless an AriaLabel holds the name still, as in
the second one here:
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 - Expanded renders
aria-expanded, for a button whose checked state is another part of the page being shown, 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 Text is read as its name
instead of being dropped - the first one below is announced as "Bold". An AriaLabel replaces it
where the spoken name should differ from the written one, and OnAriaLabel/OffAriaLabel let
that name change with the state - useful when it 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
AriaControls points at the element the toggle button controls, and where that element is a part of
the page the checked state reveals, the Expanded mode is what says so - a screen reader then
announces the button as collapsed or expanded rather than as pressed, which is the part that tells the
user something appeared elsewhere. AriaDescription adds a visually hidden description read after
the name:
Expands the details panel below the button.
The details panel is visible.
Underneath all of it is a real <button>, so Enter and Space toggle it, Tab reaches it, and the
focus ring is drawn for the keyboard and not for the mouse. Where the toggle button belongs to a larger
pattern, a role or an aria-* attribute written on it by hand is kept beside what it writes
itself, and naming a pattern of its own takes the state attribute with it: aria-pressed is a state
of the button role alone, so a role that reads aria-checked instead - a checkbox, an
option in a listbox - is given that state, kept in step with IsChecked without a second
attribute to maintain:
Cascading parameters
A toolbar of BitToggleButtons usually repeats the same handful of parameters on every button.
BitParams takes them out of the markup: it cascades a BitToggleButtonParams down to every
BitToggleButton underneath it, however deeply nested. Every property of that class is nullable, so only
the ones you actually set travel; the rest are left alone.
Here Variant and IconOnly are set once for the whole group. A value written on a button
itself always wins - the cascade only fills in what the markup left alone - which is why the last one
below keeps its own Text variant:
The starting state is cascaded through DefaultIsChecked rather than through IsChecked. The
checked state itself is deliberately left out of BitToggleButtonParams: it is the one parameter a
BitToggleButton assigns to itself on every click, so a cascaded value would be written straight back over
the click on the next render. DefaultIsChecked is only read while the button initializes, which is
what makes it the safe way to start a whole group off checked:
Parameters is a list, so a single BitParams can carry the parameters of several component
types at once - a BitToggleButtonParams next to a BitActionButtonParams, each one reaching
only the components it belongs to.
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 presets scale the text, the icon, the padding and the spinner together, and each one takes the
control height of its size as a floor, so a BitToggleButton lines up with the other controls beside it in
a toolbar. Icon-only ones become squares of that same height.
Icon-only, at the same three sizes:
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:
Saving...
The BitToggleButton reads a set of
CSS variables off its root. The two states have their own,
so restyling the resting look never quietly takes the state indication with it. They inherit, so a value on
:root or any ancestor re-skins every toggle button below it, and one on the Style of an
instance re-skins that one and any toggle button nested in it. They restyle the default, not a choice: an
explicit Color (or OnColor / OffColor) or Size wins over the variables for what
it sets.
CSS variables:
Set once on an ancestor, inherited by every BitToggleButton inside it:
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.
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 it - and any instance nested inside it, which inherits the value too; a parameter changes one alone,
as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps
one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or
font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component
falls back to the theme token beside it.
BitToggleButton CSS variables
| Name | Default value | Description |
|---|---|---|
| --bit-ToggleButton-color | Per Variant: --bit-clr-pri-text (Fill), --bit-clr-pri (Outline, Text) | Foreground of the unchecked toggle button at rest. The checked state paints its own, so setting this one alone never changes how the state reads. The Color parameter (or OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-color, --bit-ToggleButton-outline-color and --bit-ToggleButton-text-color are read ahead of it. |
| --bit-ToggleButton-background | Per Variant: --bit-clr-pri (Fill), transparent (Outline, Text) | Background of the unchecked toggle button at rest, and the fallback of its resting border color. The Color parameter (or OffColor) wins over it in Fill; the transparent background of Outline and Text is its alone. Shared by the three variants: --bit-ToggleButton-fill-background, --bit-ToggleButton-outline-background and --bit-ToggleButton-text-background are read ahead of it. |
| --bit-ToggleButton-border-color | --bit-ToggleButton-background, then per Variant | Border color of the unchecked toggle button at rest. The Outline variant is the one that draws it in the role color while the background stays transparent. The Color parameter (or OffColor) wins over it, except over the transparent border of Text. Shared by the three variants: --bit-ToggleButton-fill-border-color, --bit-ToggleButton-outline-border-color and --bit-ToggleButton-text-border-color are read ahead of it. |
| --bit-ToggleButton-hover-color | Per Variant: the resting foreground (Fill), --bit-clr-pri-text (Outline, Text) | Foreground while hovered, on pointer devices only, and the one an unchecked Outline or Text toggle button with FixedColor wears in every state. The Color parameter (or OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-hover-color, --bit-ToggleButton-outline-hover-color and --bit-ToggleButton-text-hover-color are read ahead of it. |
| --bit-ToggleButton-hover-background | --bit-clr-pri-hover | Background while hovered, and the fallback of the hovered border color. The Color parameter (or OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-hover-background, --bit-ToggleButton-outline-hover-background and --bit-ToggleButton-text-hover-background are read ahead of it. |
| --bit-ToggleButton-hover-border-color | --bit-ToggleButton-hover-background | Border color while hovered. Set it on its own to keep an outline steady under a changing background. The Color parameter (or OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-hover-border-color, --bit-ToggleButton-outline-hover-border-color and --bit-ToggleButton-text-hover-border-color are read ahead of it. |
| --bit-ToggleButton-active-color | --bit-ToggleButton-hover-color | Foreground while pressed. The Color parameter (or OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-active-color, --bit-ToggleButton-outline-active-color and --bit-ToggleButton-text-active-color are read ahead of it. |
| --bit-ToggleButton-active-background | --bit-clr-pri-active | Background while pressed, and the fallback of the pressed border color. The Color parameter (or OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-active-background, --bit-ToggleButton-outline-active-background and --bit-ToggleButton-text-active-background are read ahead of it. |
| --bit-ToggleButton-active-border-color | --bit-ToggleButton-active-background | Border color while pressed. The Color parameter (or OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-active-border-color, --bit-ToggleButton-outline-active-border-color and --bit-ToggleButton-text-active-border-color are read ahead of it. |
| --bit-ToggleButton-checked-color | --bit-clr-pri-text | Foreground while checked, in every variant. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-hover-color | --bit-ToggleButton-checked-color | Foreground while checked and hovered, on pointer devices only. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-active-color | --bit-ToggleButton-checked-hover-color | Foreground while checked and pressed. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-background | --bit-clr-pri-dark | Background while checked, and the fallback of the checked border color. It is what separates the two states visually, so it stays worth keeping distinct from the resting background. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-border-color | --bit-ToggleButton-checked-background | Border color while checked. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-hover-background | --bit-clr-pri-dark-hover | Background while checked and hovered. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-hover-border-color | --bit-ToggleButton-checked-hover-background | Border color while checked and hovered. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-active-background | --bit-clr-pri-dark-active | Background while checked and pressed. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-checked-active-border-color | --bit-ToggleButton-checked-active-background | Border color while checked and pressed. The Color parameter (or OnColor) wins over it. |
| --bit-ToggleButton-disabled-color | --bit-clr-pri-dis-text | Foreground when Disabled is true; also the focus ring color of a disabled toggle button kept focusable with AllowDisabledFocus. The Color parameter (or OnColor / OffColor) wins over it. Shared by the three variants: --bit-ToggleButton-fill-disabled-color, --bit-ToggleButton-outline-disabled-color and --bit-ToggleButton-text-disabled-color are read ahead of it. |
| --bit-ToggleButton-disabled-background | Per Variant: --bit-clr-pri-dis (Fill), transparent (Outline, Text) | Background when Disabled is true. The Color parameter (or OnColor / OffColor) wins over it in Fill; the transparent background of Outline and Text is its alone. Shared by the three variants: --bit-ToggleButton-fill-disabled-background, --bit-ToggleButton-outline-disabled-background and --bit-ToggleButton-text-disabled-background are read ahead of it. |
| --bit-ToggleButton-disabled-border-color | --bit-ToggleButton-disabled-background, then per Variant | Border color when Disabled is true. The Color parameter (or OnColor / OffColor) wins over it, except over the transparent border of Text. Shared by the three variants: --bit-ToggleButton-fill-disabled-border-color, --bit-ToggleButton-outline-disabled-border-color and --bit-ToggleButton-text-disabled-border-color are read ahead of it. |
| --bit-ToggleButton-fill-color | --bit-ToggleButton-color | Foreground at rest of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-background | --bit-ToggleButton-background | Background at rest of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-border-color | --bit-ToggleButton-border-color | Border color at rest of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-hover-color | --bit-ToggleButton-hover-color | Foreground while hovered (pointer devices only) of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-hover-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-hover-background | --bit-ToggleButton-hover-background | Background while hovered (pointer devices only) of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-hover-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-hover-border-color | --bit-ToggleButton-hover-border-color | Border color while hovered (pointer devices only) of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-hover-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-active-color | --bit-ToggleButton-active-color | Foreground while pressed of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-active-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-active-background | --bit-ToggleButton-active-background | Background while pressed of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-active-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-active-border-color | --bit-ToggleButton-active-border-color | Border color while pressed of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-active-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-fill-disabled-color | --bit-ToggleButton-disabled-color | Foreground when disabled of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-disabled-color so a theme can set this variant apart from the other two. It also draws the focus ring of a disabled toggle button of this variant, checked or not, while AllowDisabledFocus keeps it in the tab order. The Color parameter (or OnColor / OffColor) wins over it. |
| --bit-ToggleButton-fill-disabled-background | --bit-ToggleButton-disabled-background | Background when disabled of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-disabled-background so a theme can set this variant apart from the other two. The Color parameter (or OnColor / OffColor) wins over it. |
| --bit-ToggleButton-fill-disabled-border-color | --bit-ToggleButton-disabled-border-color | Border color when disabled of an unchecked Fill toggle button alone, read ahead of --bit-ToggleButton-disabled-border-color so a theme can set this variant apart from the other two. The Color parameter (or OnColor / OffColor) wins over it. |
| --bit-ToggleButton-outline-color | --bit-ToggleButton-color | Foreground at rest of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-background | --bit-ToggleButton-background | Background at rest of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) leaves it alone. |
| --bit-ToggleButton-outline-border-color | --bit-ToggleButton-border-color | Border color at rest of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-hover-color | --bit-ToggleButton-hover-color | Foreground while hovered (pointer devices only) of an unchecked Outline toggle button alone, and the one it wears in every state with FixedColor, read ahead of --bit-ToggleButton-hover-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-hover-background | --bit-ToggleButton-hover-background | Background while hovered (pointer devices only) of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-hover-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-hover-border-color | --bit-ToggleButton-hover-border-color | Border color while hovered (pointer devices only) of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-hover-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-active-color | --bit-ToggleButton-active-color | Foreground while pressed of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-active-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-active-background | --bit-ToggleButton-active-background | Background while pressed of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-active-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-active-border-color | --bit-ToggleButton-active-border-color | Border color while pressed of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-active-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-outline-disabled-color | --bit-ToggleButton-disabled-color | Foreground when disabled of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-disabled-color so a theme can set this variant apart from the other two. It also draws the focus ring of a disabled toggle button of this variant, checked or not, while AllowDisabledFocus keeps it in the tab order. The Color parameter (or OnColor / OffColor) wins over it. |
| --bit-ToggleButton-outline-disabled-background | --bit-ToggleButton-disabled-background | Background when disabled of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-disabled-background so a theme can set this variant apart from the other two. The Color parameter (or OnColor / OffColor) leaves it alone. |
| --bit-ToggleButton-outline-disabled-border-color | --bit-ToggleButton-disabled-border-color | Border color when disabled of an unchecked Outline toggle button alone, read ahead of --bit-ToggleButton-disabled-border-color so a theme can set this variant apart from the other two. The Color parameter (or OnColor / OffColor) wins over it. |
| --bit-ToggleButton-text-color | --bit-ToggleButton-color | Foreground at rest of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-text-background | --bit-ToggleButton-background | Background at rest of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) leaves it alone. |
| --bit-ToggleButton-text-border-color | --bit-ToggleButton-border-color | Border color at rest of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) leaves it alone. |
| --bit-ToggleButton-text-hover-color | --bit-ToggleButton-hover-color | Foreground while hovered (pointer devices only) of an unchecked Text toggle button alone, and the one it wears in every state with FixedColor, read ahead of --bit-ToggleButton-hover-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-text-hover-background | --bit-ToggleButton-hover-background | Background while hovered (pointer devices only) of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-hover-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-text-hover-border-color | --bit-ToggleButton-hover-border-color | Border color while hovered (pointer devices only) of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-hover-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-text-active-color | --bit-ToggleButton-active-color | Foreground while pressed of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-active-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-text-active-background | --bit-ToggleButton-active-background | Background while pressed of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-active-background so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-text-active-border-color | --bit-ToggleButton-active-border-color | Border color while pressed of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-active-border-color so a theme can set this variant apart from the other two. The Color parameter (or OffColor) wins over it. |
| --bit-ToggleButton-text-disabled-color | --bit-ToggleButton-disabled-color | Foreground when disabled of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-disabled-color so a theme can set this variant apart from the other two. It also draws the focus ring of a disabled toggle button of this variant, checked or not, while AllowDisabledFocus keeps it in the tab order. The Color parameter (or OnColor / OffColor) wins over it. |
| --bit-ToggleButton-text-disabled-background | --bit-ToggleButton-disabled-background | Background when disabled of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-disabled-background so a theme can set this variant apart from the other two. The Color parameter (or OnColor / OffColor) leaves it alone. |
| --bit-ToggleButton-text-disabled-border-color | --bit-ToggleButton-disabled-border-color | Border color when disabled of an unchecked Text toggle button alone, read ahead of --bit-ToggleButton-disabled-border-color so a theme can set this variant apart from the other two. The Color parameter (or OnColor / OffColor) leaves it alone. |
| --bit-ToggleButton-checked-disabled-opacity | --bit-opa-dis | Dimming of a disabled toggle button that is checked. It keeps the checked colors rather than taking the disabled ones, since a setting greyed out at "on" and one greyed out at "off" are different facts, so the disabled variables above do not reach it; set it to 1 to remove the dimming and leave it in its checked colors at full strength, and restyle it through the checked variables. |
| --bit-ToggleButton-focus-color | --bit-clr-pri-focus | Color of the keyboard focus ring. The Color parameter (or OnColor / OffColor) 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-ToggleButton-radius | --bit-shp-radius-button | Corner radius of the box, which the background and the focus ring follow. Set it to 999px for the pill-shaped toggle buttons of a filter row. |
| --bit-ToggleButton-border-width | --bit-shp-brd-width | Thickness of the border. The Fill and Text variants draw theirs in the background color, so thickening it only shows on Outline unless a border color is set with it. |
| --bit-ToggleButton-min-width | --bit-siz-ctrl-min-width | Smallest width of the box. An icon-only toggle button falls back to its minimum height rather than to the control minimum, which is what keeps it square, and a FullWidth one drops the minimum altogether, since a button measured by its container should not be pushed out of one narrower than it. A value set here is honoured in both cases. |
| --bit-ToggleButton-min-height | --bit-siz-ctrl-md | Smallest height of the box, which is what lines a toggle button up with the other controls of its size and keeps the smallest one above the 24px minimum pointer target of WCAG 2.2. It is a floor, not a height: a wrapped label still grows the box. It is also the minimum width of an icon-only toggle button. The Size parameter wins over it. |
| --bit-ToggleButton-padding | --bit-siz-ctrl-pad-y-md --bit-siz-ctrl-pad-x-md, --bit-siz-ctrl-pad-y-md when icon-only | Padding of the box. The Size parameter wins over it. |
| --bit-ToggleButton-gap | spacing(0.5), 0 when there is no text | Room between the check mark, the icon and the text. |
| --bit-ToggleButton-font-size | --bit-tpg-fs-sm | Font size of the text. The Size parameter wins over it. |
| --bit-ToggleButton-font-weight | --bit-tpg-font-weight | Font weight of the text. Raising it on the checked state alone is not possible from here, since one box carries both states; use Styles.Checked for that. |
| --bit-ToggleButton-icon-size | The text size, or spacing(2.35) when icon-only | Size of the icon and the check mark. With a label beside it the glyph rides the text by default, which is what keeps the two lined up at any font scale. The Size parameter wins over it on an icon-only toggle button. |
| --bit-ToggleButton-spinner-size | spacing(2.35) | Diameter of the spinner shown in the loading state. The Size parameter wins over it. |
| --bit-ToggleButton-loading-label-font-size | --bit-tpg-fs-xs | Font size of the LoadingLabel beside the spinner, one step of the ramp below the text of the toggle button. The Size parameter wins over it. |
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). Where the controlled element is a part of the page the checked state reveals, pair it with the Expanded AriaMode. |
| 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 for as long as the OnClick, OnChanging and OnChange callbacks take, preventing subsequent clicks by default. ToggleAsync takes the same path. |
| 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. An explicit value wins over the --bit-ToggleButton-* color variables, the checked ones included; left unset, the toggle button is primary unless they say otherwise. |
| 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 press. The color it holds is the one that reads against the Color role, which the Outline and Text variants otherwise only swap in once a fill appears behind the content. |
| FullWidth | bool | false | Expands the toggle button width to 100% of the available width. The minimum width of the size class goes with it, so the toggle button is never pushed out of a container narrower than the minimum. |
| 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. The wording is not thrown away with the text: where no AriaLabel is given, the Text of the state becomes the accessible name, and a LoadingLabel is announced rather than shown beside the spinner. |
| IconPlacement | BitPlacement? | null | The position of the icon relative to the content of the toggle button. The default value is Start. Only Start and End are honoured, and they follow the reading direction; any other value leaves the icon where Start would put it. |
| 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 covers its content with a spinner and prevents subsequent clicks unless Reclickable is enabled. While the clicks are refused the toggle button renders aria-disabled beside aria-busy, and the content stays in place behind the spinner, so the accessible name does not disappear while it is busy. |
| LoadingDelay | int | 0 | The delay in milliseconds before the spinner appears after the toggle button enters the loading state, which keeps a fast toggle from flashing one. The click guard of the loading state applies immediately regardless of the delay. |
| LoadingLabel | string? | null | The loading label text to show next to the spinner icon. It is also announced by a live region beside the toggle button when the loading state begins. On an IconOnly toggle button the announcement is all of it: the label is not shown, since it would stretch the square while it lasts. |
| LoadingLabelPlacement | BitPlacement | BitPlacement.End | The position of the loading label in regards to the spinner icon. Only Top, Bottom, Start and End are honoured; any other value falls back to the default. |
| LoadingTemplate | RenderFragment? | null | The custom template used to replace the default content of the toggle button in the loading state. |
| NoWrap | bool | false | Keeps the text of the toggle button on a single line and ends it with an ellipsis where it does not fit. |
| 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. An explicit value wins over the --bit-ToggleButton-* color variables while unchecked. |
| 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. A template that differs from the one of the other state usually changes the accessible name with it, which the automatic AriaMode cannot detect the way it detects a changing text; set AriaLabel or AriaMode to settle it. |
| 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. With no other wording to name the toggle button, the tooltip becomes its accessible name, so a title that differs per state suppresses aria-pressed just as a per-state text does. |
| 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. An explicit value wins over the --bit-ToggleButton-checked-* color variables while checked. |
| 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. A template that differs from the one of the other state usually changes the accessible name with it, which the automatic AriaMode cannot detect the way it detects a changing text; set AriaLabel or AriaMode to settle it. |
| 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. With no other wording to name the toggle button, the tooltip becomes its accessible name, so a title that differs per state suppresses aria-pressed just as a per-state text does. |
| 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. A loading toggle button otherwise stops responding to the pointer altogether, keeping neither the hover shade nor the pointer cursor of a control that takes clicks. |
| ShowCheckMark | bool | false | Renders a check mark in the checked state so the state is not conveyed by color alone, which is also what keeps the state readable in Windows High Contrast. It is part of the default body, so a toggle button given a template renders none. |
| Size | BitSize? | null | The size of the toggle button. An explicit value wins over the --bit-ToggleButton-* size variables; left unset, the toggle button is medium unless they say otherwise. |
| 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. |
| 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. |
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. |
| Expanded | 4 | Renders aria-expanded instead of aria-pressed, for a toggle button whose checked state is another part of the page being shown. |
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. |
| 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. |
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.