Toggle button

A toggle button switches one labeled setting, such as mute or bold, on and off, and stays on until you switch it off. Its variant sets how much attention the setting draws, and a built-in badge adds a count with no extra element to place. Press the toggles below, and watch the badge and the icons change on their own.

Mic Bold Italic Wi-Fi Alerts Loop Shuffle Sync Inbox Pin Lock Bold Italic Wi-Fi Theme Loop Shuffle Pin Focus Alerts Mute Liked Pin Subtitles Captions Sync Lock Bold Theme Loop Pin Focus Mute Fav Sync Lock Alerts

Reference docs⁠

BlazorReactWebOverviewExamplesAPIStylingAccessibility

Choosing a button⁠

Six components share the button's form. Each suits a different job:

  • Button: an action with a name, such as Save, Send invitation, or Delete project.
  • Icon button: an action shown by a relevant icon only, with no label, such as close, share, or more, where space is tight.
  • Floating action button: the one most important action on a screen, floating above the content.
  • FAB menu: a floating action button that opens a short set of related actions, such as new message, new call, or new meeting.
  • Toggle button: a labeled setting that stays on until it is switched off, such as bold or mute.
  • Toggle icon button: the same two-state setting, shown by an icon only, such as bookmark or favorite.

Two jobs belong elsewhere. Words that take the reader somewhere are a link in the text, and a choice among options is a set of chips, radio buttons, or a select.

Choosing a variant⁠

The variants set how much attention a toggle button draws, from most to least:

  • Filled: a setting that changes what happens next, such as record or mute during a call.
  • Tonal: a middle ground, such as bold in an editing toolbar.
  • Outlined: an important but secondary setting, such as loop or shuffle in a player.
  • Elevated: a setting that needs separation from a patterned background, such as subtitles over video.

The text variant is drawn as outlined, because a toggle button has no text style.

Built in⁠

  • selected holds the on or off state, and a click flips it and fires input, then change.
  • selected-icon-name and the selected-label slot swap the icon and the label while the button is on.
  • badge-value adds a count with no separate element to place.
  • tooltip-value adds a tooltip that a screen reader reads as the button's description.
  • Its touch target is 48 by 48 pixels even when it paints smaller, as touch-target explains.
  • soft-disabled keeps a disabled button reachable by keyboard and screen reader.

Using toggle buttons well⁠

  • Set an outlined icon for the off state and a filled icon for the on state, with selected-icon-name.
  • Put the icon before the label, the only place the icon slot sits.
  • Let the label and the icon set the width; a toggle button that fills a row looks like a bar, not a setting.

These rules follow Material 3 Expressive's guidance for buttons, on material.io.

Variants⁠

variant sets the container's color, outline, and shadow. Omit it and the toggle button takes the variant from your style configuration, which is text unless you have changed it. A toggle button draws text as outlined, so choose one of the other four to set the emphasis; the Overview says when to use each.

Selected state⁠

selected is the on or off state, and a click flips it. Setting selected from code changes the button but fires no event. Press the toggle button, or use the switch, to see the state change.

Size⁠

size sets the height, corner radius, padding, icon size, and label text style, from extra-small to extra-large. Omit it and the toggle button takes the size from your style configuration, which is small unless you have changed it.

touch-target sets how the touch target is sized; omit it and it takes overflow from your style configuration. Except with none, the target is at least 48 by 48 pixels. With overflow the target extends past the painted button, and with wrapper the button takes the target's size.

Icons⁠

icon-name shows a Material Symbols icon before the label, and selected-icon-name replaces it while the button is on. The icon and selected-icon slots do the same with your own icons and take precedence over the names. Give the selected-label slot a second label, and it replaces the default label while the button is on.

flip-icon-in-rtl mirrors the icon-name icon, and flip-selected-icon-in-rtl mirrors the selected-icon-name icon, on a right-to-left page. Slotted icons are never mirrored. Use the switch to turn mirroring on.

Badges⁠

badge-value shows text on the badge. badge-dot shows a small dot instead, whether or not badge-value is set. badge-concealed hides the badge and keeps its settings, so clearing it shows the same badge again. Use the switches to try each.

Tooltips⁠

tooltip-value sets the tooltip's text. It opens on hover and on focus, and a screen reader reads it as the button's description. tooltip-position sets where it sits, and has no effect without tooltip-value. Omit it and the tooltip takes end-center from your style configuration.

Forms⁠

A toggle button is not a form control. name identifies the toggle button. It submits nothing, so read selected for the state.

Disabled and soft-disabled⁠

disabled takes the button out of the Tab order, so it cannot be focused or pressed. soft-disabled keeps it focusable and in the Tab order with aria-disabled="true", and the component swallows the click; a handler registered in the capture phase still sees it. Use the switches to try each.

Properties⁠

PropertyAttributeTypeDescription
badgeConcealedbadge-concealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbadge-dotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuebadge-valuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disableddisabledbooleandefault falseDisables the button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
flipIconInRtlflip-icon-in-rtlbooleandefault falseMirrors the iconName icon when the text direction is right to left. An icon in the icon slot is not mirrored. See Icons.
flipSelectedIconInRtlflip-selected-icon-in-rtlbooleandefault falseFlips the selected icon supplied by the selected-icon-name property in RTL mode. See Icons.
formread-onlyHTMLFormElementThe form the component belongs to, or null when it has none.
iconNameicon-namestringThe name of a Material Symbols icon, shown before the label. The icon slot overrides it, and the button logs a warning when both are set. See Icons.
namenamestringThe name a cw-toggle-button-group knows this button by: the group's value, the form data it submits and its change event's value carry it. The button submits nothing itself. See Forms.
selectedselectedbooleandefault falseSets the selected state. When true, the button shows its selected icon and selected label, from the selected-icon slot or selectedIconName and the selected-label slot. Each falls back to the default when none is provided. See Selected state, Forms.
selectedIconNameselected-icon-namestringA Material Symbols icon name. An alternative to the selected-icon slot. If both are provided, the selected-icon slot takes precedence, and a warning is logged. See Icons.
sizesizeextra-small, small, medium, large, extra-largeSizeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.Small, from the style configurationThe button's size, from extra-small to extra-large. It sets the button's height, corner radius, padding, icon size, and the label's text style. See Size.
softDisabledsoft-disabledbooleandefault falseDisables the button but keeps it focusable and in the Tab order. It carries aria-disabled="true", and a click on it does nothing and does not bubble past the button; a capture-phase listener still receives it. Use it when a disabled button must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositiontooltip-positionstart-start, start-center, start-end, center-start, center-end, end-start, end-center, end-endTooltipPositionTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuetooltip-valuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargettouch-targetnone, overflow, wrapperTouchTargetTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationHow the button's touch target is sized. Except with none, the target is at least 48 by 48 pixels.
  • overflow: the button keeps its visual size, and the touch target extends past it.
  • wrapper: the button takes the touch target's size, around its visual size.
  • none: the touch target is the button's visual size.
See Size.
variantvariantelevated, filled, tonal, outlined, textButtonVariantButtonVariant.Elevated, .Filled, .Tonal, .Outlined, .Textdefault ButtonVariant.Outlined, drawn for the style configuration's ButtonVariant.TextThe button's emphasis. A toggle button has no text look: it draws text as outlined. See Variants.

Slots⁠

SlotDescription
(default)The button's label. It shows in both states unless a selected-label is provided.
iconThe icon to display. It shows in both states unless a selected-icon is provided.
selected-iconThe icon to display when selected.
selected-labelThe label to display when selected.

Events⁠

EventTypeDetailDescription
clickMouseEvent—Dispatched when the button is clicked. A disabled or soft-disabled button does not dispatch it. It bubbles, is composed, and is cancelable.
inputInputEvent—Dispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles and is composed.
changeEvent—Dispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles.

A click toggles selected, then fires input and change. Setting selected from code fires neither.

Props⁠

PropTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseDisables the button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseMirrors the iconName icon when the text direction is right to left. An icon in the slot="icon" child is not mirrored. See Icons.
flipSelectedIconInRtlbooleandefault falseFlips the selected icon supplied by the selectedIconName prop in RTL mode. See Icons.
formread-only (ref)HTMLFormElementThe form the component belongs to, or null when it has none.
iconNamestringThe name of a Material Symbols icon, shown before the label. The slot="icon" child overrides it, and the button logs a warning when both are set. See Icons.
namestringThe name a CrToggleButtonGroup knows this button by: the group's value, the form data it submits and its change event's value carry it. The button submits nothing itself. See Forms.
selectedbooleandefault falseSets the selected state. When true, the button shows its selected icon and selected label, from the slot="selected-icon" child or selectedIconName and the slot="selected-label" child. Each falls back to the default when none is provided. See Selected state, Forms.
selectedIconNamestringA Material Symbols icon name. An alternative to the slot="selected-icon" child. If both are provided, the slot="selected-icon" child takes precedence, and a warning is logged. See Icons.
sizeSizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.Small, from the style configurationThe button's size, from extra-small to extra-large. It sets the button's height, corner radius, padding, icon size, and the label's text style. See Size.
softDisabledbooleandefault falseDisables the button but keeps it focusable and in the Tab order. It carries aria-disabled="true", and a click on it does nothing and does not bubble past the button; a capture-phase listener still receives it. Use it when a disabled button must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationHow the button's touch target is sized. Except with none, the target is at least 48 by 48 pixels.
  • overflow: the button keeps its visual size, and the touch target extends past it.
  • wrapper: the button takes the touch target's size, around its visual size.
  • none: the touch target is the button's visual size.
See Size.
variantButtonVariantTypeButtonVariant.Elevated, .Filled, .Tonal, .Outlined, .Textdefault ButtonVariant.Outlined, drawn for the style configuration's ButtonVariant.TextThe button's emphasis. A toggle button has no text look: it draws text as outlined. See Variants.

Children⁠

ChildDescription
childrenThe button's label. It shows in both states unless a selected-label is provided.
a child with slot="icon"The icon to display. It shows in both states unless a selected-icon is provided.
a child with slot="selected-icon"The icon to display when selected.
a child with slot="selected-label"The label to display when selected.

Events⁠

PropArgumentDescription
onClickReact.MouseEvent<HTMLElement>Dispatched when the button is clicked. A disabled or soft-disabled button does not dispatch it. It bubbles, is composed, and is cancelable.
onInputReact.ChangeEvent<HTMLInputElement>Dispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles and is composed.
onChangeReact.ChangeEvent<HTMLInputElement>Dispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles.

A click toggles selected, then fires input and change. Setting selected from code fires neither.

Parameters⁠

ParameterTypeDescription
BadgeConcealedbool?default falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
BadgeDotbool?default falseShows the badge as a small dot with no text, whether or not BadgeValue is set. See Badges.
BadgeValuestring?The badge's text. While it is empty and BadgeDot is not set, no badge renders. Ignored if BadgeDot is set. See Badges.
Disabledbool?default falseDisables the button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
FlipIconInRtlbool?default falseMirrors the IconName icon when the text direction is right to left. An icon in the Icon render fragment is not mirrored. See Icons.
FlipSelectedIconInRtlbool?default falseFlips the selected icon supplied by the SelectedIconName parameter in RTL mode. See Icons.
IconNamestring?The name of a Material Symbols icon, shown before the label. The Icon render fragment overrides it, and the button logs a warning when both are set. See Icons.
Namestring?The name a CbToggleButtonGroup knows this button by: the group's value, the form data it submits and its change event's value carry it. The button submits nothing itself. See Forms.
SelectedIconNamestring?A Material Symbols icon name. An alternative to the SelectedIcon render fragment. If both are provided, the SelectedIcon render fragment takes precedence, and a warning is logged. See Icons.
SizeSize?Size.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.Small, from the style configurationThe button's size, from extra-small to extra-large. It sets the button's height, corner radius, padding, icon size, and the label's text style. See Size.
SoftDisabledbool?default falseDisables the button but keeps it focusable and in the Tab order. It carries aria-disabled="true", and a click on it does nothing and does not bubble past the button; a capture-phase listener still receives it. Use it when a disabled button must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
TooltipPositionTooltipPosition?TooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without TooltipValue. See Tooltips.
TooltipValuestring?The tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
TouchTargetTouchTarget?TouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationHow the button's touch target is sized. Except with none, the target is at least 48 by 48 pixels.
  • overflow: the button keeps its visual size, and the touch target extends past it.
  • wrapper: the button takes the touch target's size, around its visual size.
  • none: the touch target is the button's visual size.
See Size.
Valuebool—
ValueExpressionExpression<Func<bool>>?Gets or sets an expression that identifies the bound value.
VariantButtonVariant?ButtonVariant.Elevated, .Filled, .Tonal, .Outlined, .Textdefault ButtonVariant.Outlined, drawn for the style configuration's ButtonVariant.TextThe button's emphasis. A toggle button has no text look: it draws text as outlined. See Variants.

Render fragments⁠

Once you write Icon or any other fragment as a child element, the main content must go in an explicit <ChildContent> too; markup beside <Icon> is a compile error. Here ChildContent is: The button's label.

<CbToggleButton>
    <Icon><CbIcon>favorite</CbIcon></Icon>
    <ChildContent>Main content</ChildContent>
</CbToggleButton>
content_copy
ParameterTypeDescription
ChildContentRenderFragment?The button's label. It shows in both states unless a selected-label is provided.
IconRenderFragment?The icon to display. It shows in both states unless a selected-icon is provided.
SelectedIconRenderFragment?The icon to display when selected.
SelectedLabelRenderFragment?The label to display when selected.

Event callbacks⁠

ParameterTypeDescription
OnClickEventCallback<MouseEventArgs>Dispatched when the button is clicked. A disabled or soft-disabled button does not dispatch it. It bubbles, is composed, and is cancelable.
OnInputEventCallback<ChangeEventArgs>Dispatched when the user toggles the button. Setting Selected in code does not dispatch it. It bubbles and is composed.
OnChangeEventCallback<ChangeEventArgs>Dispatched when the user toggles the button. Setting Selected in code does not dispatch it. It bubbles.

A click toggles selected, then fires input and change. Setting selected from code fires neither.

Inputs⁠

InputTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseDisables the button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseMirrors the iconName icon when the text direction is right to left. An icon in the icon slot is not mirrored. See Icons.
flipSelectedIconInRtlbooleandefault falseFlips the selected icon supplied by the selectedIconName input in RTL mode. See Icons.
iconNamestringThe name of a Material Symbols icon, shown before the label. The icon slot overrides it, and the button logs a warning when both are set. See Icons.
namestringThe name a CaToggleButtonGroup knows this button by: the group's value, the form data it submits and its change event's value carry it. The button submits nothing itself. See Forms.
selectedbooleandefault falseSets the selected state. When true, the button shows its selected icon and selected label, from the selected-icon slot or selectedIconName and the selected-label slot. Each falls back to the default when none is provided. See Selected state, Forms.
selectedIconNamestringA Material Symbols icon name. An alternative to the selected-icon slot. If both are provided, the selected-icon slot takes precedence, and a warning is logged. See Icons.
sizeSizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.Small, from the style configurationThe button's size, from extra-small to extra-large. It sets the button's height, corner radius, padding, icon size, and the label's text style. See Size.
softDisabledbooleandefault falseDisables the button but keeps it focusable and in the Tab order. It carries aria-disabled="true", and a click on it does nothing and does not bubble past the button; a capture-phase listener still receives it. Use it when a disabled button must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationHow the button's touch target is sized. Except with none, the target is at least 48 by 48 pixels.
  • overflow: the button keeps its visual size, and the touch target extends past it.
  • wrapper: the button takes the touch target's size, around its visual size.
  • none: the touch target is the button's visual size.
See Size.
valueboolean—
variantButtonVariantTypeButtonVariant.Elevated, .Filled, .Tonal, .Outlined, .Textdefault ButtonVariant.Outlined, drawn for the style configuration's ButtonVariant.TextThe button's emphasis. A toggle button has no text look: it draws text as outlined. See Variants.

Content projection⁠

ContentDescription
content with no slotThe button's label. It shows in both states unless a selected-label is provided.
an element with slot="icon"The icon to display. It shows in both states unless a selected-icon is provided.
an element with slot="selected-icon"The icon to display when selected.
an element with slot="selected-label"The label to display when selected.

Outputs⁠

OutputEventDescription
cwClickMouseEventDispatched when the button is clicked. A disabled or soft-disabled button does not dispatch it. It bubbles, is composed, and is cancelable.
cwInputInputEventDispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles and is composed.
cwChangeEventDispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles.

A click toggles selected, then fires input and change. Setting selected from code fires neither.

Props⁠

PropTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseDisables the button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseMirrors the iconName icon when the text direction is right to left. An icon in the icon slot is not mirrored. See Icons.
flipSelectedIconInRtlbooleandefault falseFlips the selected icon supplied by the selectedIconName prop in RTL mode. See Icons.
iconNamestringThe name of a Material Symbols icon, shown before the label. The icon slot overrides it, and the button logs a warning when both are set. See Icons.
namestringThe name a CvToggleButtonGroup knows this button by: the group's value, the form data it submits and its change event's value carry it. The button submits nothing itself. See Forms.
selectedbooleandefault falseSets the selected state. When true, the button shows its selected icon and selected label, from the selected-icon slot or selectedIconName and the selected-label slot. Each falls back to the default when none is provided. See Selected state, Forms.
selectedIconNamestringA Material Symbols icon name. An alternative to the selected-icon slot. If both are provided, the selected-icon slot takes precedence, and a warning is logged. See Icons.
sizeSizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.Small, from the style configurationThe button's size, from extra-small to extra-large. It sets the button's height, corner radius, padding, icon size, and the label's text style. See Size.
softDisabledbooleandefault falseDisables the button but keeps it focusable and in the Tab order. It carries aria-disabled="true", and a click on it does nothing and does not bubble past the button; a capture-phase listener still receives it. Use it when a disabled button must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationHow the button's touch target is sized. Except with none, the target is at least 48 by 48 pixels.
  • overflow: the button keeps its visual size, and the touch target extends past it.
  • wrapper: the button takes the touch target's size, around its visual size.
  • none: the touch target is the button's visual size.
See Size.
variantButtonVariantTypeButtonVariant.Elevated, .Filled, .Tonal, .Outlined, .Textdefault ButtonVariant.Outlined, drawn for the style configuration's ButtonVariant.TextThe button's emphasis. A toggle button has no text look: it draws text as outlined. See Variants.

Slots⁠

SlotDescription
defaultThe button's label. It shows in both states unless a selected-label is provided.
iconThe icon to display. It shows in both states unless a selected-icon is provided.
selected-iconThe icon to display when selected.
selected-labelThe label to display when selected.

Events⁠

EventTypeDescription
clickMouseEventDispatched when the button is clicked. A disabled or soft-disabled button does not dispatch it. It bubbles, is composed, and is cancelable.
inputInputEventDispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles and is composed.
changeEventDispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles.

A click toggles selected, then fires input and change. Setting selected from code fires neither.

Props⁠

PropTypeDescription
badgeConcealedbooleandefault falseHides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
badgeDotbooleandefault falseShows the badge as a small dot with no text, whether or not badgeValue is set. See Badges.
badgeValuestringThe badge's text. While it is empty and badgeDot is not set, no badge renders. Ignored if badgeDot is set. See Badges.
disabledbooleandefault falseDisables the button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
flipIconInRtlbooleandefault falseMirrors the iconName icon when the text direction is right to left. An icon in the iconSnippet snippet is not mirrored. See Icons.
flipSelectedIconInRtlbooleandefault falseFlips the selected icon supplied by the selectedIconName prop in RTL mode. See Icons.
iconNamestringThe name of a Material Symbols icon, shown before the label. The iconSnippet snippet overrides it, and the button logs a warning when both are set. See Icons.
namestringThe name a CsToggleButtonGroup knows this button by: the group's value, the form data it submits and its change event's value carry it. The button submits nothing itself. See Forms.
selectedbooleandefault falseSets the selected state. When true, the button shows its selected icon and selected label, from the selectedIconSnippet snippet or selectedIconName and the selectedLabelSnippet snippet. Each falls back to the default when none is provided. See Selected state, Forms.
selectedIconNamestringA Material Symbols icon name. An alternative to the selectedIconSnippet snippet. If both are provided, the selectedIconSnippet snippet takes precedence, and a warning is logged. See Icons.
sizeSizeTypeSize.ExtraSmall, .Small, .Medium, .Large, .ExtraLargedefault Size.Small, from the style configurationThe button's size, from extra-small to extra-large. It sets the button's height, corner radius, padding, icon size, and the label's text style. See Size.
softDisabledbooleandefault falseDisables the button but keeps it focusable and in the Tab order. It carries aria-disabled="true", and a click on it does nothing and does not bubble past the button; a capture-phase listener still receives it. Use it when a disabled button must stay reachable by keyboard and screen reader. For when this is needed, see WAI-ARIA Authoring Practices: disabled controls. See Disabled and soft-disabled.
tooltipPositionTooltipPositionTypeTooltipPosition.StartStart, .StartCenter, .StartEnd, .CenterStart, .CenterEnd, .EndStart, .EndCenter, .EndEnddefault TooltipPosition.EndCenter, from the style configurationWhere the tooltip appears around the element, such as above or beside it. It has no effect without tooltipValue. See Tooltips.
tooltipValuestringThe tooltip's text. The tooltip opens on hover and on focus, and a screen reader announces it as the control's description unless it only repeats the control's name. No tooltip renders while it is empty. See Tooltips.
touchTargetTouchTargetTypeTouchTarget.None, .Overflow, .Wrapperdefault TouchTarget.Overflow, from the style configurationHow the button's touch target is sized. Except with none, the target is at least 48 by 48 pixels.
  • overflow: the button keeps its visual size, and the touch target extends past it.
  • wrapper: the button takes the touch target's size, around its visual size.
  • none: the touch target is the button's visual size.
See Size.
variantButtonVariantTypeButtonVariant.Elevated, .Filled, .Tonal, .Outlined, .Textdefault ButtonVariant.Outlined, drawn for the style configuration's ButtonVariant.TextThe button's emphasis. A toggle button has no text look: it draws text as outlined. See Variants.

Snippets⁠

SnippetDescription
childrenThe button's label. It shows in both states unless a selected-label is provided.
iconSnippetThe icon to display. It shows in both states unless a selected-icon is provided.
selectedIconSnippetThe icon to display when selected.
selectedLabelSnippetThe label to display when selected.

Events⁠

PropTypeDescription
onClickMouseEventDispatched when the button is clicked. A disabled or soft-disabled button does not dispatch it. It bubbles, is composed, and is cancelable.
onInputInputEventDispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles and is composed.
onChangeEventDispatched when the user toggles the button. Setting selected in code does not dispatch it. It bubbles.

A click toggles selected, then fires input and change. Setting selected from code fires neither.

Each attribute value has its own tokens; a cell shows its token's value, and selecting the cell shows the token's fallback path, with each name and value ready to copy. For example, the outlined column's container-color row is --ct-button-outlined-container-color, which defaults to transparent.

Variant⁠

Nameelevatedfilledoutlinedtexttonal
container-color--ct-sys-color-surface-container-low --ct-button-elevated-container-color--ct-sys-color-primary --ct-button-filled-container-colortransparent --ct-button-outlined-container-colortransparent --ct-button-text-container-color--ct-sys-color-secondary-container --ct-button-tonal-container-color
container-elevation1 --ct-button-elevated-container-elevation0 --ct-button-filled-container-elevation0 --ct-button-outlined-container-elevation0 --ct-button-text-container-elevation0 --ct-button-tonal-container-elevation
icon-color--ct-sys-color-primary --ct-button-elevated-icon-color--ct-sys-color-on-primary --ct-button-filled-icon-color--ct-sys-color-on-surface-variant --ct-button-outlined-icon-color--ct-sys-color-primary --ct-button-text-icon-color--ct-sys-color-on-secondary-container --ct-button-tonal-icon-color
label-text-color--ct-sys-color-primary --ct-button-elevated-label-text-color--ct-sys-color-on-primary --ct-button-filled-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-label-text-color--ct-sys-color-primary --ct-button-text-label-text-color--ct-sys-color-on-secondary-container --ct-button-tonal-label-text-color
outline-colortransparent --ct-button-elevated-outline-colortransparent --ct-button-filled-outline-color--ct-sys-color-outline-variant --ct-button-outlined-outline-colortransparent --ct-button-text-outline-colortransparent --ct-button-tonal-outline-color
state-layer-color--ct-sys-color-primary --ct-button-elevated-state-layer-color--ct-sys-color-on-primary --ct-button-filled-state-layer-color--ct-sys-color-on-surface-variant --ct-button-outlined-state-layer-color--ct-sys-color-primary --ct-button-text-state-layer-color--ct-sys-color-on-secondary-container --ct-button-tonal-state-layer-color
selected-container-color--ct-sys-color-primary --ct-button-elevated-selected-container-color--ct-sys-color-primary --ct-button-filled-selected-container-color--ct-sys-color-inverse-surface --ct-button-outlined-selected-container-colorsame as container-color --ct-button-text-selected-container-color--ct-sys-color-secondary --ct-button-tonal-selected-container-color
selected-icon-color--ct-sys-color-on-primary --ct-button-elevated-selected-icon-color--ct-sys-color-on-primary --ct-button-filled-selected-icon-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-icon-colorsame as icon-color --ct-button-text-selected-icon-color--ct-sys-color-on-secondary --ct-button-tonal-selected-icon-color
selected-label-text-color--ct-sys-color-on-primary --ct-button-elevated-selected-label-text-color--ct-sys-color-on-primary --ct-button-filled-selected-label-text-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-label-text-colorsame as label-text-color --ct-button-text-selected-label-text-color--ct-sys-color-on-secondary --ct-button-tonal-selected-label-text-color
selected-outline-colortransparent --ct-button-elevated-selected-outline-colortransparent --ct-button-filled-selected-outline-colortransparent --ct-button-outlined-selected-outline-colortransparent --ct-button-text-selected-outline-colortransparent --ct-button-tonal-selected-outline-color
unselected-container-color--ct-sys-color-surface-container-low --ct-button-elevated-unselected-container-color--ct-sys-color-surface-container --ct-button-filled-unselected-container-colorsame as container-color --ct-button-outlined-unselected-container-colorsame as container-color --ct-button-text-unselected-container-color--ct-sys-color-secondary-container --ct-button-tonal-unselected-container-color
unselected-icon-color--ct-sys-color-primary --ct-button-elevated-unselected-icon-color--ct-sys-color-on-surface-variant --ct-button-filled-unselected-icon-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-icon-colorsame as icon-color --ct-button-text-unselected-icon-color--ct-sys-color-on-secondary-container --ct-button-tonal-unselected-icon-color
unselected-label-text-color--ct-sys-color-primary --ct-button-elevated-unselected-label-text-color--ct-sys-color-on-surface-variant --ct-button-filled-unselected-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-label-text-colorsame as label-text-color --ct-button-text-unselected-label-text-color--ct-sys-color-on-secondary-container --ct-button-tonal-unselected-label-text-color
hover-icon-colorsame as icon-color --ct-button-elevated-hover-icon-colorsame as icon-color --ct-button-filled-hover-icon-color--ct-sys-color-on-surface-variant --ct-button-outlined-hover-icon-colorsame as icon-color --ct-button-text-hover-icon-colorsame as icon-color --ct-button-tonal-hover-icon-color
hover-label-text-colorsame as label-text-color --ct-button-elevated-hover-label-text-colorsame as label-text-color --ct-button-filled-hover-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-hover-label-text-colorsame as label-text-color --ct-button-text-hover-label-text-colorsame as label-text-color --ct-button-tonal-hover-label-text-color
hover-state-layer-colorsame as state-layer-color --ct-button-elevated-hover-state-layer-colorsame as state-layer-color --ct-button-filled-hover-state-layer-color--ct-sys-color-on-surface-variant --ct-button-outlined-hover-state-layer-colorsame as state-layer-color --ct-button-text-hover-state-layer-colorsame as state-layer-color --ct-button-tonal-hover-state-layer-color
hover-state-layer-opacity--ct-sys-state-hover-state-layer-opacity --ct-button-elevated-hover-state-layer-opacity--ct-sys-state-hover-state-layer-opacity --ct-button-filled-hover-state-layer-opacity--ct-sys-state-hover-state-layer-opacity --ct-button-outlined-hover-state-layer-opacity--ct-sys-state-hover-state-layer-opacity --ct-button-text-hover-state-layer-opacity--ct-sys-state-hover-state-layer-opacity --ct-button-tonal-hover-state-layer-opacity
selected-hover-icon-colorsame as selected-icon-color --ct-button-elevated-selected-hover-icon-colorsame as selected-icon-color --ct-button-filled-selected-hover-icon-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-hover-icon-colorsame as selected-icon-color --ct-button-text-selected-hover-icon-colorsame as selected-icon-color --ct-button-tonal-selected-hover-icon-color
selected-hover-label-text-colorsame as selected-label-text-color --ct-button-elevated-selected-hover-label-text-colorsame as selected-label-text-color --ct-button-filled-selected-hover-label-text-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-hover-label-text-colorsame as selected-label-text-color --ct-button-text-selected-hover-label-text-colorsame as selected-label-text-color --ct-button-tonal-selected-hover-label-text-color
selected-hover-state-layer-colorsame as selected-label-text-color --ct-button-elevated-selected-hover-state-layer-colorsame as selected-label-text-color --ct-button-filled-selected-hover-state-layer-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-hover-state-layer-colorsame as selected-label-text-color --ct-button-text-selected-hover-state-layer-colorsame as selected-label-text-color --ct-button-tonal-selected-hover-state-layer-color
unselected-hover-icon-colorsame as unselected-icon-color --ct-button-elevated-unselected-hover-icon-colorsame as unselected-icon-color --ct-button-filled-unselected-hover-icon-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-hover-icon-colorsame as unselected-icon-color --ct-button-text-unselected-hover-icon-colorsame as unselected-icon-color --ct-button-tonal-unselected-hover-icon-color
unselected-hover-label-text-colorsame as unselected-label-text-color --ct-button-elevated-unselected-hover-label-text-colorsame as unselected-label-text-color --ct-button-filled-unselected-hover-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-hover-label-text-colorsame as unselected-label-text-color --ct-button-text-unselected-hover-label-text-colorsame as unselected-label-text-color --ct-button-tonal-unselected-hover-label-text-color
unselected-hover-state-layer-colorsame as unselected-label-text-color --ct-button-elevated-unselected-hover-state-layer-colorsame as unselected-label-text-color --ct-button-filled-unselected-hover-state-layer-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-hover-state-layer-colorsame as unselected-label-text-color --ct-button-text-unselected-hover-state-layer-colorsame as unselected-label-text-color --ct-button-tonal-unselected-hover-state-layer-color
focus-icon-colorsame as icon-color --ct-button-elevated-focus-icon-colorsame as icon-color --ct-button-filled-focus-icon-color--ct-sys-color-on-surface-variant --ct-button-outlined-focus-icon-colorsame as icon-color --ct-button-text-focus-icon-colorsame as icon-color --ct-button-tonal-focus-icon-color
focus-label-text-colorsame as label-text-color --ct-button-elevated-focus-label-text-colorsame as label-text-color --ct-button-filled-focus-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-focus-label-text-colorsame as label-text-color --ct-button-text-focus-label-text-colorsame as label-text-color --ct-button-tonal-focus-label-text-color
selected-focus-icon-colorsame as selected-icon-color --ct-button-elevated-selected-focus-icon-colorsame as selected-icon-color --ct-button-filled-selected-focus-icon-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-focus-icon-colorsame as selected-icon-color --ct-button-text-selected-focus-icon-colorsame as selected-icon-color --ct-button-tonal-selected-focus-icon-color
selected-focus-label-text-colorsame as selected-label-text-color --ct-button-elevated-selected-focus-label-text-colorsame as selected-label-text-color --ct-button-filled-selected-focus-label-text-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-focus-label-text-colorsame as selected-label-text-color --ct-button-text-selected-focus-label-text-colorsame as selected-label-text-color --ct-button-tonal-selected-focus-label-text-color
unselected-focus-icon-colorsame as unselected-icon-color --ct-button-elevated-unselected-focus-icon-colorsame as unselected-icon-color --ct-button-filled-unselected-focus-icon-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-focus-icon-colorsame as unselected-icon-color --ct-button-text-unselected-focus-icon-colorsame as unselected-icon-color --ct-button-tonal-unselected-focus-icon-color
unselected-focus-label-text-colorsame as unselected-label-text-color --ct-button-elevated-unselected-focus-label-text-colorsame as unselected-label-text-color --ct-button-filled-unselected-focus-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-focus-label-text-colorsame as unselected-label-text-color --ct-button-text-unselected-focus-label-text-colorsame as unselected-label-text-color --ct-button-tonal-unselected-focus-label-text-color
pressed-label-text-colorsame as label-text-color --ct-button-elevated-pressed-label-text-colorsame as label-text-color --ct-button-filled-pressed-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-pressed-label-text-colorsame as label-text-color --ct-button-text-pressed-label-text-colorsame as label-text-color --ct-button-tonal-pressed-label-text-color
pressed-state-layer-colorsame as state-layer-color --ct-button-elevated-pressed-state-layer-colorsame as state-layer-color --ct-button-filled-pressed-state-layer-color--ct-sys-color-on-surface-variant --ct-button-outlined-pressed-state-layer-colorsame as state-layer-color --ct-button-text-pressed-state-layer-colorsame as state-layer-color --ct-button-tonal-pressed-state-layer-color
pressed-state-layer-opacity--ct-sys-state-pressed-state-layer-opacity --ct-button-elevated-pressed-state-layer-opacity--ct-sys-state-pressed-state-layer-opacity --ct-button-filled-pressed-state-layer-opacity--ct-sys-state-pressed-state-layer-opacity --ct-button-outlined-pressed-state-layer-opacity--ct-sys-state-pressed-state-layer-opacity --ct-button-text-pressed-state-layer-opacity--ct-sys-state-pressed-state-layer-opacity --ct-button-tonal-pressed-state-layer-opacity
selected-pressed-label-text-colorsame as selected-label-text-color --ct-button-elevated-selected-pressed-label-text-colorsame as selected-label-text-color --ct-button-filled-selected-pressed-label-text-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-pressed-label-text-colorsame as selected-label-text-color --ct-button-text-selected-pressed-label-text-colorsame as selected-label-text-color --ct-button-tonal-selected-pressed-label-text-color
selected-pressed-state-layer-colorsame as selected-label-text-color --ct-button-elevated-selected-pressed-state-layer-colorsame as selected-label-text-color --ct-button-filled-selected-pressed-state-layer-color--ct-sys-color-inverse-on-surface --ct-button-outlined-selected-pressed-state-layer-colorsame as selected-label-text-color --ct-button-text-selected-pressed-state-layer-colorsame as selected-label-text-color --ct-button-tonal-selected-pressed-state-layer-color
unselected-pressed-label-text-colorsame as unselected-label-text-color --ct-button-elevated-unselected-pressed-label-text-colorsame as unselected-label-text-color --ct-button-filled-unselected-pressed-label-text-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-pressed-label-text-colorsame as unselected-label-text-color --ct-button-text-unselected-pressed-label-text-colorsame as unselected-label-text-color --ct-button-tonal-unselected-pressed-label-text-color
unselected-pressed-state-layer-colorsame as unselected-label-text-color --ct-button-elevated-unselected-pressed-state-layer-colorsame as unselected-label-text-color --ct-button-filled-unselected-pressed-state-layer-color--ct-sys-color-on-surface-variant --ct-button-outlined-unselected-pressed-state-layer-colorsame as unselected-label-text-color --ct-button-text-unselected-pressed-state-layer-colorsame as unselected-label-text-color --ct-button-tonal-unselected-pressed-state-layer-color
disabled-container-color--ct-sys-color-on-surface --ct-button-elevated-disabled-container-color--ct-sys-color-on-surface --ct-button-filled-disabled-container-colortransparent --ct-button-outlined-disabled-container-colortransparent --ct-button-text-disabled-container-color--ct-sys-color-on-surface --ct-button-tonal-disabled-container-color
disabled-container-elevation0 --ct-button-elevated-disabled-container-elevation0 --ct-button-filled-disabled-container-elevation0 --ct-button-outlined-disabled-container-elevation0 --ct-button-text-disabled-container-elevation0 --ct-button-tonal-disabled-container-elevation
disabled-container-opacity0.1 --ct-button-elevated-disabled-container-opacity0.1 --ct-button-filled-disabled-container-opacity0 --ct-button-outlined-disabled-container-opacity0 --ct-button-text-disabled-container-opacity0.1 --ct-button-tonal-disabled-container-opacity
disabled-icon-color--ct-sys-color-on-surface --ct-button-elevated-disabled-icon-color--ct-sys-color-on-surface --ct-button-filled-disabled-icon-color--ct-sys-color-on-surface --ct-button-outlined-disabled-icon-color--ct-sys-color-on-surface --ct-button-text-disabled-icon-color--ct-sys-color-on-surface --ct-button-tonal-disabled-icon-color
disabled-icon-opacity0.38 --ct-button-elevated-disabled-icon-opacity0.38 --ct-button-filled-disabled-icon-opacity0.38 --ct-button-outlined-disabled-icon-opacity0.38 --ct-button-text-disabled-icon-opacity0.38 --ct-button-tonal-disabled-icon-opacity
disabled-label-text-color--ct-sys-color-on-surface --ct-button-elevated-disabled-label-text-color--ct-sys-color-on-surface --ct-button-filled-disabled-label-text-color--ct-sys-color-on-surface --ct-button-outlined-disabled-label-text-color--ct-sys-color-on-surface --ct-button-text-disabled-label-text-color--ct-sys-color-on-surface --ct-button-tonal-disabled-label-text-color
disabled-label-text-opacity0.38 --ct-button-elevated-disabled-label-text-opacity0.38 --ct-button-filled-disabled-label-text-opacity0.38 --ct-button-outlined-disabled-label-text-opacity0.38 --ct-button-text-disabled-label-text-opacity0.38 --ct-button-tonal-disabled-label-text-opacity
disabled-outline-colorsame as outline-color --ct-button-elevated-disabled-outline-colorsame as outline-color --ct-button-filled-disabled-outline-color--ct-sys-color-outline-variant --ct-button-outlined-disabled-outline-colorsame as outline-color --ct-button-text-disabled-outline-colorsame as outline-color --ct-button-tonal-disabled-outline-color
disabled-outline-opacity0.38 --ct-button-elevated-disabled-outline-opacity0.38 --ct-button-filled-disabled-outline-opacity0.38 --ct-button-outlined-disabled-outline-opacity0.38 --ct-button-text-disabled-outline-opacity0.38 --ct-button-tonal-disabled-outline-opacity
selected-disabled-container-colorsame as container-color --ct-button-elevated-selected-disabled-container-colorsame as container-color --ct-button-filled-selected-disabled-container-color--ct-sys-color-on-surface --ct-button-outlined-selected-disabled-container-colorsame as container-color --ct-button-text-selected-disabled-container-colorsame as container-color --ct-button-tonal-selected-disabled-container-color
large-outline-width0px --ct-button-elevated-large-outline-width0px --ct-button-filled-large-outline-width2px --ct-button-outlined-large-outline-width0px --ct-button-text-large-outline-width0px --ct-button-tonal-large-outline-width
medium-outline-width0px --ct-button-elevated-medium-outline-width0px --ct-button-filled-medium-outline-width1px --ct-button-outlined-medium-outline-width0px --ct-button-text-medium-outline-width0px --ct-button-tonal-medium-outline-width
small-outline-width0px --ct-button-elevated-small-outline-width0px --ct-button-filled-small-outline-width1px --ct-button-outlined-small-outline-width0px --ct-button-text-small-outline-width0px --ct-button-tonal-small-outline-width
xlarge-outline-width0px --ct-button-elevated-xlarge-outline-width0px --ct-button-filled-xlarge-outline-width3px --ct-button-outlined-xlarge-outline-width0px --ct-button-text-xlarge-outline-width0px --ct-button-tonal-xlarge-outline-width
xsmall-outline-width0px --ct-button-elevated-xsmall-outline-width0px --ct-button-filled-xsmall-outline-width1px --ct-button-outlined-xsmall-outline-width0px --ct-button-text-xsmall-outline-width0px --ct-button-tonal-xsmall-outline-width
large-selected-outline-width0px --ct-button-elevated-large-selected-outline-width0px --ct-button-filled-large-selected-outline-width0px --ct-button-outlined-large-selected-outline-width0px --ct-button-text-large-selected-outline-width0px --ct-button-tonal-large-selected-outline-width
medium-selected-outline-width0px --ct-button-elevated-medium-selected-outline-width0px --ct-button-filled-medium-selected-outline-width0px --ct-button-outlined-medium-selected-outline-width0px --ct-button-text-medium-selected-outline-width0px --ct-button-tonal-medium-selected-outline-width
small-selected-outline-width0px --ct-button-elevated-small-selected-outline-width0px --ct-button-filled-small-selected-outline-width0px --ct-button-outlined-small-selected-outline-width0px --ct-button-text-small-selected-outline-width0px --ct-button-tonal-small-selected-outline-width
xlarge-selected-outline-width0px --ct-button-elevated-xlarge-selected-outline-width0px --ct-button-filled-xlarge-selected-outline-width0px --ct-button-outlined-xlarge-selected-outline-width0px --ct-button-text-xlarge-selected-outline-width0px --ct-button-tonal-xlarge-selected-outline-width
xsmall-selected-outline-width0px --ct-button-elevated-xsmall-selected-outline-width0px --ct-button-filled-xsmall-selected-outline-width0px --ct-button-outlined-xsmall-selected-outline-width0px --ct-button-text-xsmall-selected-outline-width0px --ct-button-tonal-xsmall-selected-outline-width

Size⁠

Token names spell extra-small as xsmall and extra-large as xlarge.

Nameextra-smallsmallmediumlargeextra-large
container-height32px --ct-button-xsmall-container-height40px --ct-button-small-container-height56px --ct-button-medium-container-height96px --ct-button-large-container-height136px --ct-button-xlarge-container-height
corner-end-end-radiussame as corner-radius --ct-button-xsmall-corner-end-end-radiussame as corner-radius --ct-button-small-corner-end-end-radiussame as corner-radius --ct-button-medium-corner-end-end-radiussame as corner-radius --ct-button-large-corner-end-end-radiussame as corner-radius --ct-button-xlarge-corner-end-end-radius
corner-end-start-radiussame as corner-radius --ct-button-xsmall-corner-end-start-radiussame as corner-radius --ct-button-small-corner-end-start-radiussame as corner-radius --ct-button-medium-corner-end-start-radiussame as corner-radius --ct-button-large-corner-end-start-radiussame as corner-radius --ct-button-xlarge-corner-end-start-radius
corner-radius--ct-sys-corner-radius-full --ct-button-xsmall-corner-radius--ct-sys-corner-radius-full --ct-button-small-corner-radius--ct-sys-corner-radius-full --ct-button-medium-corner-radius--ct-sys-corner-radius-full --ct-button-large-corner-radius--ct-sys-corner-radius-full --ct-button-xlarge-corner-radius
corner-start-end-radiussame as corner-radius --ct-button-xsmall-corner-start-end-radiussame as corner-radius --ct-button-small-corner-start-end-radiussame as corner-radius --ct-button-medium-corner-start-end-radiussame as corner-radius --ct-button-large-corner-start-end-radiussame as corner-radius --ct-button-xlarge-corner-start-end-radius
corner-start-start-radiussame as corner-radius --ct-button-xsmall-corner-start-start-radiussame as corner-radius --ct-button-small-corner-start-start-radiussame as corner-radius --ct-button-medium-corner-start-start-radiussame as corner-radius --ct-button-large-corner-start-start-radiussame as corner-radius --ct-button-xlarge-corner-start-start-radius
icon-label-space8px --ct-button-xsmall-icon-label-space8px --ct-button-small-icon-label-space8px --ct-button-medium-icon-label-space12px --ct-button-large-icon-label-space16px --ct-button-xlarge-icon-label-space
icon-size20px --ct-button-xsmall-icon-size20px --ct-button-small-icon-size24px --ct-button-medium-icon-size32px --ct-button-large-icon-size40px --ct-button-xlarge-icon-size
label-text-font--ct-sys-typescale-label-large-font --ct-button-xsmall-label-text-font--ct-sys-typescale-label-large-font --ct-button-small-label-text-font--ct-sys-typescale-title-medium-font --ct-button-medium-label-text-font--ct-sys-typescale-headline-small-font --ct-button-large-label-text-font--ct-sys-typescale-headline-large-font --ct-button-xlarge-label-text-font
label-text-line-height--ct-sys-typescale-label-large-line-height --ct-button-xsmall-label-text-line-height--ct-sys-typescale-label-large-line-height --ct-button-small-label-text-line-height--ct-sys-typescale-title-medium-line-height --ct-button-medium-label-text-line-height--ct-sys-typescale-headline-small-line-height --ct-button-large-label-text-line-height--ct-sys-typescale-headline-large-line-height --ct-button-xlarge-label-text-line-height
label-text-size--ct-sys-typescale-label-large-size --ct-button-xsmall-label-text-size--ct-sys-typescale-label-large-size --ct-button-small-label-text-size--ct-sys-typescale-title-medium-size --ct-button-medium-label-text-size--ct-sys-typescale-headline-small-size --ct-button-large-label-text-size--ct-sys-typescale-headline-large-size --ct-button-xlarge-label-text-size
label-text-tracking--ct-sys-typescale-label-large-tracking --ct-button-xsmall-label-text-tracking--ct-sys-typescale-label-large-tracking --ct-button-small-label-text-tracking--ct-sys-typescale-title-medium-tracking --ct-button-medium-label-text-tracking--ct-sys-typescale-headline-small-tracking --ct-button-large-label-text-tracking--ct-sys-typescale-headline-large-tracking --ct-button-xlarge-label-text-tracking
label-text-weight--ct-sys-typescale-label-large-weight --ct-button-xsmall-label-text-weight--ct-sys-typescale-label-large-weight --ct-button-small-label-text-weight--ct-sys-typescale-title-medium-weight --ct-button-medium-label-text-weight--ct-sys-typescale-headline-small-weight --ct-button-large-label-text-weight--ct-sys-typescale-headline-large-weight --ct-button-xlarge-label-text-weight
leading-space12px --ct-button-xsmall-leading-space16px --ct-button-small-leading-space24px --ct-button-medium-leading-space48px --ct-button-large-leading-space64px --ct-button-xlarge-leading-space
trailing-space12px --ct-button-xsmall-trailing-space16px --ct-button-small-trailing-space24px --ct-button-medium-trailing-space48px --ct-button-large-trailing-space64px --ct-button-xlarge-trailing-space
selected-corner-end-end-radiussame as selected-corner-radius --ct-button-xsmall-selected-corner-end-end-radiussame as selected-corner-radius --ct-button-small-selected-corner-end-end-radiussame as selected-corner-radius --ct-button-medium-selected-corner-end-end-radiussame as selected-corner-radius --ct-button-large-selected-corner-end-end-radiussame as selected-corner-radius --ct-button-xlarge-selected-corner-end-end-radius
selected-corner-end-start-radiussame as selected-corner-radius --ct-button-xsmall-selected-corner-end-start-radiussame as selected-corner-radius --ct-button-small-selected-corner-end-start-radiussame as selected-corner-radius --ct-button-medium-selected-corner-end-start-radiussame as selected-corner-radius --ct-button-large-selected-corner-end-start-radiussame as selected-corner-radius --ct-button-xlarge-selected-corner-end-start-radius
selected-corner-radius--ct-sys-corner-radius-medium --ct-button-xsmall-selected-corner-radius--ct-sys-corner-radius-medium --ct-button-small-selected-corner-radius--ct-sys-corner-radius-large --ct-button-medium-selected-corner-radius--ct-sys-corner-radius-extra-large --ct-button-large-selected-corner-radius--ct-sys-corner-radius-extra-large --ct-button-xlarge-selected-corner-radius
selected-corner-start-end-radiussame as selected-corner-radius --ct-button-xsmall-selected-corner-start-end-radiussame as selected-corner-radius --ct-button-small-selected-corner-start-end-radiussame as selected-corner-radius --ct-button-medium-selected-corner-start-end-radiussame as selected-corner-radius --ct-button-large-selected-corner-start-end-radiussame as selected-corner-radius --ct-button-xlarge-selected-corner-start-end-radius
selected-corner-start-start-radiussame as selected-corner-radius --ct-button-xsmall-selected-corner-start-start-radiussame as selected-corner-radius --ct-button-small-selected-corner-start-start-radiussame as selected-corner-radius --ct-button-medium-selected-corner-start-start-radiussame as selected-corner-radius --ct-button-large-selected-corner-start-start-radiussame as selected-corner-radius --ct-button-xlarge-selected-corner-start-start-radius
pressed-corner-end-end-radiussame as pressed-corner-radius --ct-button-xsmall-pressed-corner-end-end-radiussame as pressed-corner-radius --ct-button-small-pressed-corner-end-end-radiussame as pressed-corner-radius --ct-button-medium-pressed-corner-end-end-radiussame as pressed-corner-radius --ct-button-large-pressed-corner-end-end-radiussame as pressed-corner-radius --ct-button-xlarge-pressed-corner-end-end-radius
pressed-corner-end-start-radiussame as pressed-corner-radius --ct-button-xsmall-pressed-corner-end-start-radiussame as pressed-corner-radius --ct-button-small-pressed-corner-end-start-radiussame as pressed-corner-radius --ct-button-medium-pressed-corner-end-start-radiussame as pressed-corner-radius --ct-button-large-pressed-corner-end-start-radiussame as pressed-corner-radius --ct-button-xlarge-pressed-corner-end-start-radius
pressed-corner-radius--ct-sys-corner-radius-small --ct-button-xsmall-pressed-corner-radius--ct-sys-corner-radius-small --ct-button-small-pressed-corner-radius--ct-sys-corner-radius-medium --ct-button-medium-pressed-corner-radius--ct-sys-corner-radius-large --ct-button-large-pressed-corner-radius--ct-sys-corner-radius-large --ct-button-xlarge-pressed-corner-radius
pressed-corner-start-end-radiussame as pressed-corner-radius --ct-button-xsmall-pressed-corner-start-end-radiussame as pressed-corner-radius --ct-button-small-pressed-corner-start-end-radiussame as pressed-corner-radius --ct-button-medium-pressed-corner-start-end-radiussame as pressed-corner-radius --ct-button-large-pressed-corner-start-end-radiussame as pressed-corner-radius --ct-button-xlarge-pressed-corner-start-end-radius
pressed-corner-start-start-radiussame as pressed-corner-radius --ct-button-xsmall-pressed-corner-start-start-radiussame as pressed-corner-radius --ct-button-small-pressed-corner-start-start-radiussame as pressed-corner-radius --ct-button-medium-pressed-corner-start-start-radiussame as pressed-corner-radius --ct-button-large-pressed-corner-start-start-radiussame as pressed-corner-radius --ct-button-xlarge-pressed-corner-start-start-radius

Other tokens⁠

These stay the same whatever the variant and size.

TokenValue
--ct-button-group-connected-container-shape--ct-sys-corner-radius-full --ct-button-group-connected-container-shape
--ct-button-group-connected-small-inner-corner--ct-sys-corner-radius-small --ct-button-group-connected-small-inner-corner
--ct-button-group-connected-small-pressed-inner-corner--ct-sys-corner-radius-extra-small --ct-button-group-connected-small-pressed-inner-corner
--ct-button-icon-fill1 --ct-button-icon-fill
--ct-button-max-width320px --ct-button-max-width
--ct-button-selected-icon-fill1 --ct-button-selected-icon-fill
--ct-button-unselected-icon-fill0 --ct-button-unselected-icon-fill

Names and states⁠

A toggle button follows the WAI-ARIA Authoring Practices: Button pattern, in its toggle form.

  • The accessible name is the label in the default slot. Give it an aria-label when the label does not name the setting.
  • Only aria-label, aria-haspopup, aria-expanded, and aria-current on a toggle button take effect; other ARIA attributes are ignored.
  • A screen reader announces the button as pressed or not pressed, tracking selected. With selected-label content, the changing label states the setting instead, and no pressed state is announced.
  • With soft-disabled, a screen reader announces the button as unavailable.
  • An icon from icon-name or selected-icon-name is hidden from assistive technology, so it never names the button. Give a slotted img an empty alt, or a slotted svg aria-hidden, when the label already names the setting.
  • The tooltip text is the button's description: a screen reader reads it after the name, unless it only repeats the name. It never names the button.

Keyboard and focus⁠

Key Action
Tab Moves focus to the toggle button, or past it
Enter Switches it on or off
Space Switches it on or off

Enter and Space work as they do on any button.

  • A focus ring shows on keyboard focus and hides on a pointer press.
  • With disabled, Tab skips the button.
  • soft-disabled keeps it in the Tab order and swallows the click, so the setting does not change. Its tooltip stays reachable by keyboard and is read as the description.

Pointer and touch⁠

  • The touch target is at least 48 by 48 pixels by default, which exceeds the 24 by 24 pixels WCAG 2.5.8 asks for. touch-target set to none makes the target the painted size, which is 32 pixels high at extra-small; the Size examples show each setting.

Display settings⁠

  • Forced colors: the container gets a 1 pixel ButtonText border, a selected button gets ActiveText, and a disabled button gets a dashed GrayText border. Hover and press draw a ButtonText border of 2 and 4 pixels, and the focus ring is a solid CanvasText outline.
  • Reduced motion: the press ripple, the focus ring animation, and the tooltip fade are skipped, and the corner change on press completes at once.
  • Right to left: nothing else mirrors. A slotted icon stays as it is.

Standards⁠

With its defaults, the toggle button meets seven WCAG 2.2 success criteria:

  • 2.1.1 Keyboard (A)
  • 2.1.2 No Keyboard Trap (A)
  • 2.5.2 Pointer Cancellation (A)
  • 2.4.7 Focus Visible (AA)
  • 2.5.8 Target Size (Minimum) (AA)
  • 1.3.1 Info and Relationships (A)
  • 1.4.13 Content on Hover or Focus (AA)

Four more depend on how you use it:

  • 4.1.2 Name, Role, Value (A): give it a name with a label, or an aria-label when it has none.
  • 2.5.3 Label in Name (A): keep the visible label's words in any aria-label.
  • 2.4.6 Headings and Labels (AA): write a label that says which setting it switches.
  • 1.1.1 Non-text Content (A): give a slotted image an alt, or mark a decorative one.