Toggle icon button

A toggle icon button switches a two-state setting, such as bookmark or mute, with one icon. Give it a selected icon and the change from off to on shows at a glance, with no label to read. Press any button below, and watch one switch and a badge come and go by itself.

Reference docs⁠

Blazor

React

Web

Overview

Examples

API

Styling

Accessibility

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⁠

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

Filled: the one setting a screen is built around, such as mute on a call.
Tonal: an important setting that should not dominate, such as shuffle in a player.
Outlined: a secondary setting beside others, such as repeat or captions.
Standard: the quietest setting in a dense toolbar, such as bookmark.

Built in⁠

A second icon for the selected state: selected-icon-name replaces icon-name while selected is set.
A touch target of 48 by 48 pixels even when the button paints smaller (touch-target).
A badge from badge-value or badge-dot, which badge-concealed hides and shows again without losing its value.
A tooltip from tooltip-value, announced to a screen reader as the button's description.
The on or off state, reported to assistive technology as pressed and operable with Enter or Space.
A click that fires input and then change, so a form handler or a framework binding reads the state.

Using them well⁠

Show the unselected state with an outlined icon and the selected state with a filled one.
Give every toggle icon button an aria-label, because the icon alone gives no name.
Choose it for a setting that stays on until switched off. Use an icon button for an action that happens once, and a toggle button when the setting has a label.
Place it in a toolbar or a compact layout, where space is tight.

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

Variants⁠

variant sets how much attention a toggle icon button draws: filled, tonal, outlined, or standard. Omit it and the button takes the variant from your style configuration, which is filled unless you have changed it. Choosing a variant says when to use each.

Size⁠

size runs from extra-small to extra-large, and the style configuration supplies small when it is omitted. width takes narrow, regular, or wide, with regular as the configured default. touch-target takes overflow (the default, overflow), none, or wrapper; Pointer and touch measures the touch target.

Icons⁠

icon-name is the icon shown while the button is off, and selected-icon-name is the icon shown once selected is set. With no selected icon, the button keeps the unselected one. A cw-icon in the default slot replaces icon-name, and one in the selected-icon slot replaces selected-icon-name. Set flip-icon-in-rtl and flip-selected-icon-in-rtl on a directional icon so it mirrors in right-to-left text.

Badges⁠

badge-value puts a short text on the button, such as a count, and badge-dot shows a dot with no text. badge-concealed hides the badge and keeps its value, so clearing it brings the same badge back.

Tooltips⁠

tooltip-value is the text of a tooltip that opens on hover and on focus. tooltip-position places it, and end-center is the configured default. title is the browser's own tooltip, a plainer alternative.

Names⁠

An icon-only button needs an aria-label. selected-aria-label swaps it for another name while selected is set, and only when aria-label is set as well. Names and states covers when to use it.

Forms⁠

A toggle icon button submits nothing with a form. Read the state from selected, which the demo ties to a variable; name identifies the toggle icon button.

Disabled and soft-disabled⁠

disabled puts the button out of keyboard reach. soft-disabled keeps it focusable, so a keyboard or screen reader user can still reach it and its tooltip, and the click does nothing. See Keyboard and focus for both.

Properties⁠

Property	Attribute	Type	Description
`autofocus`	`autofocus`	`boolean`default `false`	Requests focus for the icon button when the page loads, as the native `autofocus` attribute does.
`badgeConcealed`	`badge-concealed`	`boolean`default `false`	Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
`badgeDot`	`badge-dot`	`boolean`default `false`	Shows the badge as a small dot with no text, whether or not `badgeValue` is set. See Badges.
`badgeValue`	`badge-value`	`string`	The badge's text. While it is empty and `badgeDot` is not set, no badge renders. Ignored if `badgeDot` is set. See Badges.
`disabled`	`disabled`	`boolean`default `false`	Disables the icon button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
`flipIconInRtl`	`flip-icon-in-rtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`flipSelectedIconInRtl`	`flip-selected-icon-in-rtl`	`boolean`default `false`	Flips the selected icon supplied by the `selected-icon-name` property in RTL mode. See Icons.
`form`read-only		`HTMLFormElement`	The form the component belongs to, or `null` when it has none.
`iconName`	`icon-name`	`string`	A Material Symbols icon name. This is an alternative to using the default slot. If both are provided, the slot takes precedence, and a warning is logged. See Icons.
`name`	`name`	`string`	The 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.
`selected`	`selected`	`boolean`default `false`	Sets the selected state. When true, the icon button shows its selected icon, from the `selected-icon` slot or `selectedIconName`, or the default icon if neither is provided. See Icons, Names, Forms.
`selectedAriaLabel`	`selected-aria-label`	`string`	The icon button's accessible name while it is selected, in place of `aria-label`. It has no effect unless `aria-label` is also set, and applies only to a toggle that is not a link. See Names.
`selectedIconName`	`selected-icon-name`	`string`	A 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.
`size`	`sizeextra-small`, `small`, `medium`, `large`, `extra-large`	`SizeSize.ExtraSmall`, `.Small`, `.Medium`, `.Large`, `.ExtraLarge`default `Size.Small`, from the style configuration	Sets how large the component is, from `extra-small` to `extra-large`. A larger size makes it taller. See Size.
`softDisabled`	`soft-disabled`	`boolean`default `false`	Disables the icon 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 icon 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.
`title`	`title`	`string`	The native tooltip the browser shows on hover. With no `aria-label`, it is also the icon button's accessible name, except on a link, which takes its name from `aria-label` only. See Tooltips.
`tooltipPosition`	`tooltip-positionstart-start`, `start-center`, `start-end`, `center-start`, `center-end`, `end-start`, `end-center`, `end-end`	`TooltipPositionTooltipPosition.StartStart`, `.StartCenter`, `.StartEnd`, `.CenterStart`, `.CenterEnd`, `.EndStart`, `.EndCenter`, `.EndEnd`default `TooltipPosition.EndCenter`, from the style configuration	Where the tooltip appears around the element, such as above or beside it. It has no effect without `tooltipValue`. See Tooltips.
`tooltipValue`	`tooltip-value`	`string`	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.
`touchTarget`	`touch-targetnone`, `overflow`, `wrapper`	`TouchTargetTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size. See Size.
`variant`	`variantfilled`, `outlined`, `standard`, `tonal`	`IconButtonVariantIconButtonVariant.Filled`, `.Outlined`, `.Standard`, `.Tonal`default `IconButtonVariant.Filled`, from the style configuration	Sets how strongly the icon button stands out from its surroundings. See Variants.
`width`	`widthnarrow`, `regular`, `wide`	`IconButtonWidthIconButtonWidth.Narrow`, `.Regular`, `.Wide`default `IconButtonWidth.Regular`, from the style configuration	Sets how wide the icon button is, without changing the size of its icon. A wider button stands out more. See Size.

Slots⁠

Slot	Description
(default)	The icon to display. It shows in both states unless a `selected-icon` is provided.
`selected-icon`	The icon to display when selected.

Only icons set with icon-name and selected-icon-name mirror in right-to-left text, and only when their flip setting is on. A slotted icon is never mirrored.

Events⁠

Event	Type	Detail	Description
`input`	`InputEvent`	—	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles and is composed.
`change`	`Event`	—	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles.

A click or an Enter or Space press that toggles selected fires input and then change. Setting selected from code fires neither, and a disabled or soft-disabled button fires neither.

Props⁠

Prop	Type	Description
`autofocus`	`boolean`default `false`	Requests focus for the icon button when the page loads, as the native `autofocus` attribute does.
`badgeConcealed`	`boolean`default `false`	Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
`badgeDot`	`boolean`default `false`	Shows the badge as a small dot with no text, whether or not `badgeValue` is set. See Badges.
`badgeValue`	`string`	The badge's text. While it is empty and `badgeDot` is not set, no badge renders. Ignored if `badgeDot` is set. See Badges.
`disabled`	`boolean`default `false`	Disables the icon button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`flipSelectedIconInRtl`	`boolean`default `false`	Flips the selected icon supplied by the `selectedIconName` prop in RTL mode. See Icons.
`form`read-only (ref)	`HTMLFormElement`	The form the component belongs to, or `null` when it has none.
`iconName`	`string`	A Material Symbols icon name. This is an alternative to using the default slot. If both are provided, the slot takes precedence, and a warning is logged. See Icons.
`name`	`string`	The 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.
`selected`	`boolean`default `false`	Sets the selected state. When true, the icon button shows its selected icon, from the `slot="selected-icon"` child or `selectedIconName`, or the default icon if neither is provided. See Icons, Names, Forms.
`selectedAriaLabel`	`string`	The icon button's accessible name while it is selected, in place of `aria-label`. It has no effect unless `aria-label` is also set, and applies only to a toggle that is not a link. See Names.
`selectedIconName`	`string`	A 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.
`size`	`SizeTypeSize.ExtraSmall`, `.Small`, `.Medium`, `.Large`, `.ExtraLarge`default `Size.Small`, from the style configuration	Sets how large the component is, from `extra-small` to `extra-large`. A larger size makes it taller. See Size.
`softDisabled`	`boolean`default `false`	Disables the icon 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 icon 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.
`title`	`string`	The native tooltip the browser shows on hover. With no `aria-label`, it is also the icon button's accessible name, except on a link, which takes its name from `aria-label` only. See Tooltips.
`tooltipPosition`	`TooltipPositionTypeTooltipPosition.StartStart`, `.StartCenter`, `.StartEnd`, `.CenterStart`, `.CenterEnd`, `.EndStart`, `.EndCenter`, `.EndEnd`default `TooltipPosition.EndCenter`, from the style configuration	Where the tooltip appears around the element, such as above or beside it. It has no effect without `tooltipValue`. See Tooltips.
`tooltipValue`	`string`	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.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size. See Size.
`variant`	`IconButtonVariantTypeIconButtonVariant.Filled`, `.Outlined`, `.Standard`, `.Tonal`default `IconButtonVariant.Filled`, from the style configuration	Sets how strongly the icon button stands out from its surroundings. See Variants.
`width`	`IconButtonWidthTypeIconButtonWidth.Narrow`, `.Regular`, `.Wide`default `IconButtonWidth.Regular`, from the style configuration	Sets how wide the icon button is, without changing the size of its icon. A wider button stands out more. See Size.

Children⁠

Child	Description
`children`	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.

Only icons set with icon-name and selected-icon-name mirror in right-to-left text, and only when their flip setting is on. A slotted icon is never mirrored.

Events⁠

Prop	Argument	Description
`onInput`	`React.ChangeEvent<HTMLInputElement>`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles and is composed.
`onChange`	`React.ChangeEvent<HTMLInputElement>`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles.

A click or an Enter or Space press that toggles selected fires input and then change. Setting selected from code fires neither, and a disabled or soft-disabled button fires neither.

Parameters⁠

Parameter	Type	Description
`Autofocus`	`bool?`default `false`	Requests focus for the icon button when the page loads, as the native `Autofocus` attribute does.
`BadgeConcealed`	`bool?`default `false`	Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
`BadgeDot`	`bool?`default `false`	Shows the badge as a small dot with no text, whether or not `BadgeValue` is set. See Badges.
`BadgeValue`	`string?`	The badge's text. While it is empty and `BadgeDot` is not set, no badge renders. Ignored if `BadgeDot` is set. See Badges.
`Disabled`	`bool?`default `false`	Disables the icon button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
`FlipIconInRtl`	`bool?`default `false`	Mirrors the `IconName` icon when the text direction is right to left. See Icons.
`FlipSelectedIconInRtl`	`bool?`default `false`	Flips the selected icon supplied by the `SelectedIconName` parameter in RTL mode. See Icons.
`IconName`	`string?`	A Material Symbols icon name. This is an alternative to using the default slot. If both are provided, the slot takes precedence, and a warning is logged. See Icons.
`Name`	`string?`	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.
`SelectedAriaLabel`	`string?`	The icon button's accessible name while it is selected, in place of `aria-label`. It has no effect unless `aria-label` is also set, and applies only to a toggle that is not a link. See Names.
`SelectedIconName`	`string?`	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.
`Size`	`Size?Size.ExtraSmall`, `.Small`, `.Medium`, `.Large`, `.ExtraLarge`default `Size.Small`, from the style configuration	Sets how large the component is, from `extra-small` to `extra-large`. A larger size makes it taller. See Size.
`SoftDisabled`	`bool?`default `false`	Disables the icon 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 icon 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.
`Title`	`string?`	The native tooltip the browser shows on hover. With no `aria-label`, it is also the icon button's accessible name, except on a link, which takes its name from `aria-label` only. See Tooltips.
`TooltipPosition`	`TooltipPosition?TooltipPosition.StartStart`, `.StartCenter`, `.StartEnd`, `.CenterStart`, `.CenterEnd`, `.EndStart`, `.EndCenter`, `.EndEnd`default `TooltipPosition.EndCenter`, from the style configuration	Where the tooltip appears around the element, such as above or beside it. It has no effect without `TooltipValue`. See Tooltips.
`TooltipValue`	`string?`	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.
`TouchTarget`	`TouchTarget?TouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size. See Size.
`Value`	`bool`	—
`ValueExpression`	`Expression<Func<bool>>?`	Gets or sets an expression that identifies the bound value.
`Variant`	`IconButtonVariant?IconButtonVariant.Filled`, `.Outlined`, `.Standard`, `.Tonal`default `IconButtonVariant.Filled`, from the style configuration	Sets how strongly the icon button stands out from its surroundings. See Variants.
`Width`	`IconButtonWidth?IconButtonWidth.Narrow`, `.Regular`, `.Wide`default `IconButtonWidth.Regular`, from the style configuration	Sets how wide the icon button is, without changing the size of its icon. A wider button stands out more. See Size.

Render fragments⁠

Once you write SelectedIcon or any other fragment as a child element, the main content must go in an explicit <ChildContent> too; markup beside <SelectedIcon> is a compile error. Here ChildContent is: The icon to display.

<CbToggleIconButton>
    <SelectedIcon><CbIcon>favorite</CbIcon></SelectedIcon>
    <ChildContent>Main content</ChildContent>
</CbToggleIconButton>

content_copy

Parameter	Type	Description
`ChildContent`	`RenderFragment?`	The icon to display. It shows in both states unless a `selected-icon` is provided.
`SelectedIcon`	`RenderFragment?`	The icon to display when selected.

Only icons set with icon-name and selected-icon-name mirror in right-to-left text, and only when their flip setting is on. A slotted icon is never mirrored.

Event callbacks⁠

Parameter	Type	Description
`OnInput`	`EventCallback<ChangeEventArgs>`	Dispatched when the user toggles the icon button. Setting `Selected` in code does not dispatch it. It bubbles and is composed.
`OnChange`	`EventCallback<ChangeEventArgs>`	Dispatched when the user toggles the icon button. Setting `Selected` in code does not dispatch it. It bubbles.

A click or an Enter or Space press that toggles selected fires input and then change. Setting selected from code fires neither, and a disabled or soft-disabled button fires neither.

Inputs⁠

Input	Type	Description
`autofocus`	`boolean`default `false`	Requests focus for the icon button when the page loads, as the native `autofocus` attribute does.
`badgeConcealed`	`boolean`default `false`	Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
`badgeDot`	`boolean`default `false`	Shows the badge as a small dot with no text, whether or not `badgeValue` is set. See Badges.
`badgeValue`	`string`	The badge's text. While it is empty and `badgeDot` is not set, no badge renders. Ignored if `badgeDot` is set. See Badges.
`disabled`	`boolean`default `false`	Disables the icon button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`flipSelectedIconInRtl`	`boolean`default `false`	Flips the selected icon supplied by the `selectedIconName` input in RTL mode. See Icons.
`iconName`	`string`	A Material Symbols icon name. This is an alternative to using the default slot. If both are provided, the slot takes precedence, and a warning is logged. See Icons.
`name`	`string`	The 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.
`selected`	`boolean`default `false`	Sets the selected state. When true, the icon button shows its selected icon, from the `selected-icon` slot or `selectedIconName`, or the default icon if neither is provided. See Icons, Names, Forms.
`selectedAriaLabel`	`string`	The icon button's accessible name while it is selected, in place of `aria-label`. It has no effect unless `aria-label` is also set, and applies only to a toggle that is not a link. See Names.
`selectedIconName`	`string`	A 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.
`size`	`SizeTypeSize.ExtraSmall`, `.Small`, `.Medium`, `.Large`, `.ExtraLarge`default `Size.Small`, from the style configuration	Sets how large the component is, from `extra-small` to `extra-large`. A larger size makes it taller. See Size.
`softDisabled`	`boolean`default `false`	Disables the icon 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 icon 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.
`title`	`string`	The native tooltip the browser shows on hover. With no `aria-label`, it is also the icon button's accessible name, except on a link, which takes its name from `aria-label` only. See Tooltips.
`tooltipPosition`	`TooltipPositionTypeTooltipPosition.StartStart`, `.StartCenter`, `.StartEnd`, `.CenterStart`, `.CenterEnd`, `.EndStart`, `.EndCenter`, `.EndEnd`default `TooltipPosition.EndCenter`, from the style configuration	Where the tooltip appears around the element, such as above or beside it. It has no effect without `tooltipValue`. See Tooltips.
`tooltipValue`	`string`	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.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size. See Size.
`value`	`boolean`	—
`variant`	`IconButtonVariantTypeIconButtonVariant.Filled`, `.Outlined`, `.Standard`, `.Tonal`default `IconButtonVariant.Filled`, from the style configuration	Sets how strongly the icon button stands out from its surroundings. See Variants.
`width`	`IconButtonWidthTypeIconButtonWidth.Narrow`, `.Regular`, `.Wide`default `IconButtonWidth.Regular`, from the style configuration	Sets how wide the icon button is, without changing the size of its icon. A wider button stands out more. See Size.

Content projection⁠

Content	Description
content with no `slot`	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.

Only icons set with icon-name and selected-icon-name mirror in right-to-left text, and only when their flip setting is on. A slotted icon is never mirrored.

Outputs⁠

Output	Event	Description
`cwInput`	`InputEvent`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles and is composed.
`cwChange`	`Event`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles.

A click or an Enter or Space press that toggles selected fires input and then change. Setting selected from code fires neither, and a disabled or soft-disabled button fires neither.

Props⁠

Prop	Type	Description
`autofocus`	`boolean`default `false`	Requests focus for the icon button when the page loads, as the native `autofocus` attribute does.
`badgeConcealed`	`boolean`default `false`	Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
`badgeDot`	`boolean`default `false`	Shows the badge as a small dot with no text, whether or not `badgeValue` is set. See Badges.
`badgeValue`	`string`	The badge's text. While it is empty and `badgeDot` is not set, no badge renders. Ignored if `badgeDot` is set. See Badges.
`disabled`	`boolean`default `false`	Disables the icon button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`flipSelectedIconInRtl`	`boolean`default `false`	Flips the selected icon supplied by the `selectedIconName` prop in RTL mode. See Icons.
`iconName`	`string`	A Material Symbols icon name. This is an alternative to using the default slot. If both are provided, the slot takes precedence, and a warning is logged. See Icons.
`name`	`string`	The 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.
`selected`	`boolean`default `false`	Sets the selected state. When true, the icon button shows its selected icon, from the `selected-icon` slot or `selectedIconName`, or the default icon if neither is provided. See Icons, Names, Forms.
`selectedAriaLabel`	`string`	The icon button's accessible name while it is selected, in place of `aria-label`. It has no effect unless `aria-label` is also set, and applies only to a toggle that is not a link. See Names.
`selectedIconName`	`string`	A 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.
`size`	`SizeTypeSize.ExtraSmall`, `.Small`, `.Medium`, `.Large`, `.ExtraLarge`default `Size.Small`, from the style configuration	Sets how large the component is, from `extra-small` to `extra-large`. A larger size makes it taller. See Size.
`softDisabled`	`boolean`default `false`	Disables the icon 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 icon 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.
`title`	`string`	The native tooltip the browser shows on hover. With no `aria-label`, it is also the icon button's accessible name, except on a link, which takes its name from `aria-label` only. See Tooltips.
`tooltipPosition`	`TooltipPositionTypeTooltipPosition.StartStart`, `.StartCenter`, `.StartEnd`, `.CenterStart`, `.CenterEnd`, `.EndStart`, `.EndCenter`, `.EndEnd`default `TooltipPosition.EndCenter`, from the style configuration	Where the tooltip appears around the element, such as above or beside it. It has no effect without `tooltipValue`. See Tooltips.
`tooltipValue`	`string`	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.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size. See Size.
`variant`	`IconButtonVariantTypeIconButtonVariant.Filled`, `.Outlined`, `.Standard`, `.Tonal`default `IconButtonVariant.Filled`, from the style configuration	Sets how strongly the icon button stands out from its surroundings. See Variants.
`width`	`IconButtonWidthTypeIconButtonWidth.Narrow`, `.Regular`, `.Wide`default `IconButtonWidth.Regular`, from the style configuration	Sets how wide the icon button is, without changing the size of its icon. A wider button stands out more. See Size.

Slots⁠

Slot	Description
`default`	The icon to display. It shows in both states unless a `selected-icon` is provided.
`selected-icon`	The icon to display when selected.

Only icons set with icon-name and selected-icon-name mirror in right-to-left text, and only when their flip setting is on. A slotted icon is never mirrored.

Events⁠

Event	Type	Description
`input`	`InputEvent`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles and is composed.
`change`	`Event`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles.

A click or an Enter or Space press that toggles selected fires input and then change. Setting selected from code fires neither, and a disabled or soft-disabled button fires neither.

Props⁠

Prop	Type	Description
`autofocus`	`boolean`default `false`	Requests focus for the icon button when the page loads, as the native `autofocus` attribute does.
`badgeConcealed`	`boolean`default `false`	Hides the badge while keeping its value and dot setting, so clearing this property shows the same badge again. See Badges.
`badgeDot`	`boolean`default `false`	Shows the badge as a small dot with no text, whether or not `badgeValue` is set. See Badges.
`badgeValue`	`string`	The badge's text. While it is empty and `badgeDot` is not set, no badge renders. Ignored if `badgeDot` is set. See Badges.
`disabled`	`boolean`default `false`	Disables the icon button: it leaves the Tab order and cannot be focused or activated. See Disabled and soft-disabled.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`flipSelectedIconInRtl`	`boolean`default `false`	Flips the selected icon supplied by the `selectedIconName` prop in RTL mode. See Icons.
`iconName`	`string`	A Material Symbols icon name. This is an alternative to using the default slot. If both are provided, the slot takes precedence, and a warning is logged. See Icons.
`name`	`string`	The 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.
`selected`	`boolean`default `false`	Sets the selected state. When true, the icon button shows its selected icon, from the `selectedIconSnippet` snippet or `selectedIconName`, or the default icon if neither is provided. See Icons, Names, Forms.
`selectedAriaLabel`	`string`	The icon button's accessible name while it is selected, in place of `aria-label`. It has no effect unless `aria-label` is also set, and applies only to a toggle that is not a link. See Names.
`selectedIconName`	`string`	A 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.
`size`	`SizeTypeSize.ExtraSmall`, `.Small`, `.Medium`, `.Large`, `.ExtraLarge`default `Size.Small`, from the style configuration	Sets how large the component is, from `extra-small` to `extra-large`. A larger size makes it taller. See Size.
`softDisabled`	`boolean`default `false`	Disables the icon 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 icon 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.
`title`	`string`	The native tooltip the browser shows on hover. With no `aria-label`, it is also the icon button's accessible name, except on a link, which takes its name from `aria-label` only. See Tooltips.
`tooltipPosition`	`TooltipPositionTypeTooltipPosition.StartStart`, `.StartCenter`, `.StartEnd`, `.CenterStart`, `.CenterEnd`, `.EndStart`, `.EndCenter`, `.EndEnd`default `TooltipPosition.EndCenter`, from the style configuration	Where the tooltip appears around the element, such as above or beside it. It has no effect without `tooltipValue`. See Tooltips.
`tooltipValue`	`string`	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.
`touchTarget`	`TouchTargetTypeTouchTarget.None`, `.Overflow`, `.Wrapper`default `TouchTarget.Overflow`, from the style configuration	The area that takes a touch, at least 48 by 48 pixels and centered on the component. `overflow` extends it past the component without changing the component's layout size, `wrapper` makes the component take up the whole area in the layout, and `none` limits it to the component's own size. See Size.
`variant`	`IconButtonVariantTypeIconButtonVariant.Filled`, `.Outlined`, `.Standard`, `.Tonal`default `IconButtonVariant.Filled`, from the style configuration	Sets how strongly the icon button stands out from its surroundings. See Variants.
`width`	`IconButtonWidthTypeIconButtonWidth.Narrow`, `.Regular`, `.Wide`default `IconButtonWidth.Regular`, from the style configuration	Sets how wide the icon button is, without changing the size of its icon. A wider button stands out more. See Size.

Snippets⁠

Snippet	Description
`children`	The icon to display. It shows in both states unless a `selected-icon` is provided.
`selectedIconSnippet`	The icon to display when selected.

Only icons set with icon-name and selected-icon-name mirror in right-to-left text, and only when their flip setting is on. A slotted icon is never mirrored.

Events⁠

Prop	Type	Description
`onInput`	`InputEvent`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles and is composed.
`onChange`	`Event`	Dispatched when the user toggles the icon button. Setting `selected` in code does not dispatch it. It bubbles.

A click or an Enter or Space press that toggles selected fires input and then change. Setting selected from code fires neither, and a disabled or soft-disabled button 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 filled column's container-color row is --ct-icon-button-filled-container-color, which defaults to --ct-sys-color-primary.

Variant⁠

Name	`filled`	`outlined`	`standard`	`tonal`
`container-color`	`--ct-sys-color-primary` `--ct-icon-button-filled-container-color`	`transparent` `--ct-icon-button-outlined-container-color`	`transparent` `--ct-icon-button-standard-container-color`	`--ct-sys-color-secondary-container` `--ct-icon-button-tonal-container-color`
`icon-color`	`--ct-sys-color-on-primary` `--ct-icon-button-filled-icon-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-outlined-icon-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-standard-icon-color`	`--ct-sys-color-on-secondary-container` `--ct-icon-button-tonal-icon-color`
`outline-color`	`transparent` `--ct-icon-button-filled-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-outlined-outline-color`	`transparent` `--ct-icon-button-standard-outline-color`	`transparent` `--ct-icon-button-tonal-outline-color`
`state-layer-color`	`--ct-sys-color-on-primary` `--ct-icon-button-filled-state-layer-color`	same as `icon-color` `--ct-icon-button-outlined-state-layer-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-standard-state-layer-color`	`--ct-sys-color-on-secondary-container` `--ct-icon-button-tonal-state-layer-color`
`selected-container-color`	same as `container-color` `--ct-icon-button-filled-selected-container-color`	`--ct-sys-color-inverse-surface` `--ct-icon-button-outlined-selected-container-color`	same as `container-color` `--ct-icon-button-standard-selected-container-color`	`--ct-sys-color-secondary` `--ct-icon-button-tonal-selected-container-color`
`selected-icon-color`	same as `icon-color` `--ct-icon-button-filled-selected-icon-color`	`--ct-sys-color-inverse-on-surface` `--ct-icon-button-outlined-selected-icon-color`	`--ct-sys-color-primary` `--ct-icon-button-standard-selected-icon-color`	`--ct-sys-color-on-secondary` `--ct-icon-button-tonal-selected-icon-color`
`unselected-container-color`	`--ct-sys-color-surface-container` `--ct-icon-button-filled-unselected-container-color`	same as `container-color` `--ct-icon-button-outlined-unselected-container-color`	same as `container-color` `--ct-icon-button-standard-unselected-container-color`	same as `container-color` `--ct-icon-button-tonal-unselected-container-color`
`unselected-icon-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-filled-unselected-icon-color`	same as `icon-color` `--ct-icon-button-outlined-unselected-icon-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-standard-unselected-icon-color`	same as `icon-color` `--ct-icon-button-tonal-unselected-icon-color`
`disabled-container-color`	`--ct-sys-color-on-surface` `--ct-icon-button-filled-disabled-container-color`	`transparent` `--ct-icon-button-outlined-disabled-container-color`	`transparent` `--ct-icon-button-standard-disabled-container-color`	`--ct-sys-color-on-surface` `--ct-icon-button-tonal-disabled-container-color`
`disabled-container-opacity`	`0.1` `--ct-icon-button-filled-disabled-container-opacity`	`0.1` `--ct-icon-button-outlined-disabled-container-opacity`	`0.1` `--ct-icon-button-standard-disabled-container-opacity`	`0.1` `--ct-icon-button-tonal-disabled-container-opacity`
`disabled-icon-color`	`--ct-sys-color-on-surface` `--ct-icon-button-filled-disabled-icon-color`	`--ct-sys-color-on-surface` `--ct-icon-button-outlined-disabled-icon-color`	`--ct-sys-color-on-surface` `--ct-icon-button-standard-disabled-icon-color`	`--ct-sys-color-on-surface` `--ct-icon-button-tonal-disabled-icon-color`
`disabled-icon-opacity`	`0.38` `--ct-icon-button-filled-disabled-icon-opacity`	`0.38` `--ct-icon-button-outlined-disabled-icon-opacity`	`0.38` `--ct-icon-button-standard-disabled-icon-opacity`	`0.38` `--ct-icon-button-tonal-disabled-icon-opacity`
`disabled-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-filled-disabled-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-outlined-disabled-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-standard-disabled-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-tonal-disabled-outline-color`
`disabled-outline-opacity`	`0.38` `--ct-icon-button-filled-disabled-outline-opacity`	`0.38` `--ct-icon-button-outlined-disabled-outline-opacity`	`0.38` `--ct-icon-button-standard-disabled-outline-opacity`	`0.38` `--ct-icon-button-tonal-disabled-outline-opacity`
`focus-icon-color`	same as `icon-color` `--ct-icon-button-filled-focus-icon-color`	same as `icon-color` `--ct-icon-button-outlined-focus-icon-color`	same as `icon-color` `--ct-icon-button-standard-focus-icon-color`	same as `icon-color` `--ct-icon-button-tonal-focus-icon-color`
`focus-outline-color`	same as `outline-color` `--ct-icon-button-filled-focus-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-outlined-focus-outline-color`	same as `outline-color` `--ct-icon-button-standard-focus-outline-color`	same as `outline-color` `--ct-icon-button-tonal-focus-outline-color`
`hover-icon-color`	same as `icon-color` `--ct-icon-button-filled-hover-icon-color`	same as `icon-color` `--ct-icon-button-outlined-hover-icon-color`	same as `icon-color` `--ct-icon-button-standard-hover-icon-color`	same as `icon-color` `--ct-icon-button-tonal-hover-icon-color`
`hover-outline-color`	same as `outline-color` `--ct-icon-button-filled-hover-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-outlined-hover-outline-color`	same as `outline-color` `--ct-icon-button-standard-hover-outline-color`	same as `outline-color` `--ct-icon-button-tonal-hover-outline-color`
`hover-state-layer-color`	same as `state-layer-color` `--ct-icon-button-filled-hover-state-layer-color`	same as `state-layer-color` `--ct-icon-button-outlined-hover-state-layer-color`	same as `state-layer-color` `--ct-icon-button-standard-hover-state-layer-color`	same as `state-layer-color` `--ct-icon-button-tonal-hover-state-layer-color`
`hover-state-layer-opacity`	`--ct-sys-state-hover-state-layer-opacity` `--ct-icon-button-filled-hover-state-layer-opacity`	`--ct-sys-state-hover-state-layer-opacity` `--ct-icon-button-outlined-hover-state-layer-opacity`	`--ct-sys-state-hover-state-layer-opacity` `--ct-icon-button-standard-hover-state-layer-opacity`	`--ct-sys-state-hover-state-layer-opacity` `--ct-icon-button-tonal-hover-state-layer-opacity`
`pressed-icon-color`	same as `icon-color` `--ct-icon-button-filled-pressed-icon-color`	same as `icon-color` `--ct-icon-button-outlined-pressed-icon-color`	same as `icon-color` `--ct-icon-button-standard-pressed-icon-color`	same as `icon-color` `--ct-icon-button-tonal-pressed-icon-color`
`pressed-outline-color`	same as `outline-color` `--ct-icon-button-filled-pressed-outline-color`	`--ct-sys-color-outline-variant` `--ct-icon-button-outlined-pressed-outline-color`	same as `outline-color` `--ct-icon-button-standard-pressed-outline-color`	same as `outline-color` `--ct-icon-button-tonal-pressed-outline-color`
`pressed-state-layer-color`	same as `state-layer-color` `--ct-icon-button-filled-pressed-state-layer-color`	same as `state-layer-color` `--ct-icon-button-outlined-pressed-state-layer-color`	same as `state-layer-color` `--ct-icon-button-standard-pressed-state-layer-color`	same as `state-layer-color` `--ct-icon-button-tonal-pressed-state-layer-color`
`pressed-state-layer-opacity`	`--ct-sys-state-pressed-state-layer-opacity` `--ct-icon-button-filled-pressed-state-layer-opacity`	`--ct-sys-state-pressed-state-layer-opacity` `--ct-icon-button-outlined-pressed-state-layer-opacity`	`--ct-sys-state-pressed-state-layer-opacity` `--ct-icon-button-standard-pressed-state-layer-opacity`	`--ct-sys-state-pressed-state-layer-opacity` `--ct-icon-button-tonal-pressed-state-layer-opacity`
`selected-disabled-container-color`	same as `disabled-container-color` `--ct-icon-button-filled-selected-disabled-container-color`	`--ct-sys-color-on-surface` `--ct-icon-button-outlined-selected-disabled-container-color`	same as `disabled-container-color` `--ct-icon-button-standard-selected-disabled-container-color`	same as `disabled-container-color` `--ct-icon-button-tonal-selected-disabled-container-color`
`selected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-filled-selected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-outlined-selected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-standard-selected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-tonal-selected-disabled-icon-color`
`selected-focus-icon-color`	same as `selected-icon-color` `--ct-icon-button-filled-selected-focus-icon-color`	same as `selected-icon-color` `--ct-icon-button-outlined-selected-focus-icon-color`	same as `selected-icon-color` `--ct-icon-button-standard-selected-focus-icon-color`	same as `selected-icon-color` `--ct-icon-button-tonal-selected-focus-icon-color`
`selected-hover-icon-color`	same as `selected-icon-color` `--ct-icon-button-filled-selected-hover-icon-color`	same as `selected-icon-color` `--ct-icon-button-outlined-selected-hover-icon-color`	same as `selected-icon-color` `--ct-icon-button-standard-selected-hover-icon-color`	same as `selected-icon-color` `--ct-icon-button-tonal-selected-hover-icon-color`
`selected-hover-state-layer-color`	same as `hover-state-layer-color` `--ct-icon-button-filled-selected-hover-state-layer-color`	same as `hover-state-layer-color` `--ct-icon-button-outlined-selected-hover-state-layer-color`	same as `hover-state-layer-color` `--ct-icon-button-standard-selected-hover-state-layer-color`	same as `hover-state-layer-color` `--ct-icon-button-tonal-selected-hover-state-layer-color`
`selected-pressed-icon-color`	same as `pressed-icon-color` `--ct-icon-button-filled-selected-pressed-icon-color`	`--ct-sys-color-inverse-on-surface` `--ct-icon-button-outlined-selected-pressed-icon-color`	`--ct-sys-color-primary` `--ct-icon-button-standard-selected-pressed-icon-color`	`--ct-sys-color-on-secondary` `--ct-icon-button-tonal-selected-pressed-icon-color`
`selected-pressed-state-layer-color`	same as `pressed-state-layer-color` `--ct-icon-button-filled-selected-pressed-state-layer-color`	`--ct-sys-color-inverse-on-surface` `--ct-icon-button-outlined-selected-pressed-state-layer-color`	`--ct-sys-color-primary` `--ct-icon-button-standard-selected-pressed-state-layer-color`	`--ct-sys-color-on-secondary` `--ct-icon-button-tonal-selected-pressed-state-layer-color`
`unselected-disabled-container-color`	same as `disabled-container-color` `--ct-icon-button-filled-unselected-disabled-container-color`	same as `disabled-container-color` `--ct-icon-button-outlined-unselected-disabled-container-color`	same as `disabled-container-color` `--ct-icon-button-standard-unselected-disabled-container-color`	same as `disabled-container-color` `--ct-icon-button-tonal-unselected-disabled-container-color`
`unselected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-filled-unselected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-outlined-unselected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-standard-unselected-disabled-icon-color`	same as `disabled-icon-color` `--ct-icon-button-tonal-unselected-disabled-icon-color`
`unselected-focus-icon-color`	same as `unselected-icon-color` `--ct-icon-button-filled-unselected-focus-icon-color`	same as `unselected-icon-color` `--ct-icon-button-outlined-unselected-focus-icon-color`	same as `unselected-icon-color` `--ct-icon-button-standard-unselected-focus-icon-color`	same as `unselected-icon-color` `--ct-icon-button-tonal-unselected-focus-icon-color`
`unselected-hover-icon-color`	same as `unselected-icon-color` `--ct-icon-button-filled-unselected-hover-icon-color`	same as `unselected-icon-color` `--ct-icon-button-outlined-unselected-hover-icon-color`	same as `unselected-icon-color` `--ct-icon-button-standard-unselected-hover-icon-color`	same as `unselected-icon-color` `--ct-icon-button-tonal-unselected-hover-icon-color`
`unselected-hover-state-layer-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-filled-unselected-hover-state-layer-color`	same as `hover-state-layer-color` `--ct-icon-button-outlined-unselected-hover-state-layer-color`	same as `hover-state-layer-color` `--ct-icon-button-standard-unselected-hover-state-layer-color`	same as `hover-state-layer-color` `--ct-icon-button-tonal-unselected-hover-state-layer-color`
`unselected-pressed-icon-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-filled-unselected-pressed-icon-color`	same as `pressed-icon-color` `--ct-icon-button-outlined-unselected-pressed-icon-color`	same as `pressed-icon-color` `--ct-icon-button-standard-unselected-pressed-icon-color`	same as `pressed-icon-color` `--ct-icon-button-tonal-unselected-pressed-icon-color`
`unselected-pressed-state-layer-color`	`--ct-sys-color-on-surface-variant` `--ct-icon-button-filled-unselected-pressed-state-layer-color`	same as `pressed-state-layer-color` `--ct-icon-button-outlined-unselected-pressed-state-layer-color`	same as `pressed-state-layer-color` `--ct-icon-button-standard-unselected-pressed-state-layer-color`	same as `pressed-state-layer-color` `--ct-icon-button-tonal-unselected-pressed-state-layer-color`
`large-outline-width`	`0px` `--ct-icon-button-filled-large-outline-width`	`2px` `--ct-icon-button-outlined-large-outline-width`	`0px` `--ct-icon-button-standard-large-outline-width`	`0px` `--ct-icon-button-tonal-large-outline-width`
`medium-outline-width`	`0px` `--ct-icon-button-filled-medium-outline-width`	`1px` `--ct-icon-button-outlined-medium-outline-width`	`0px` `--ct-icon-button-standard-medium-outline-width`	`0px` `--ct-icon-button-tonal-medium-outline-width`
`small-outline-width`	`0px` `--ct-icon-button-filled-small-outline-width`	`1px` `--ct-icon-button-outlined-small-outline-width`	`0px` `--ct-icon-button-standard-small-outline-width`	`0px` `--ct-icon-button-tonal-small-outline-width`
`xlarge-outline-width`	`0px` `--ct-icon-button-filled-xlarge-outline-width`	`3px` `--ct-icon-button-outlined-xlarge-outline-width`	`0px` `--ct-icon-button-standard-xlarge-outline-width`	`0px` `--ct-icon-button-tonal-xlarge-outline-width`
`xsmall-outline-width`	`0px` `--ct-icon-button-filled-xsmall-outline-width`	`1px` `--ct-icon-button-outlined-xsmall-outline-width`	`0px` `--ct-icon-button-standard-xsmall-outline-width`	`0px` `--ct-icon-button-tonal-xsmall-outline-width`
`large-selected-outline-width`	`0px` `--ct-icon-button-filled-large-selected-outline-width`	`0px` `--ct-icon-button-outlined-large-selected-outline-width`	`0px` `--ct-icon-button-standard-large-selected-outline-width`	`0px` `--ct-icon-button-tonal-large-selected-outline-width`
`medium-selected-outline-width`	`0px` `--ct-icon-button-filled-medium-selected-outline-width`	`0px` `--ct-icon-button-outlined-medium-selected-outline-width`	`0px` `--ct-icon-button-standard-medium-selected-outline-width`	`0px` `--ct-icon-button-tonal-medium-selected-outline-width`
`small-selected-outline-width`	`0px` `--ct-icon-button-filled-small-selected-outline-width`	`0px` `--ct-icon-button-outlined-small-selected-outline-width`	`0px` `--ct-icon-button-standard-small-selected-outline-width`	`0px` `--ct-icon-button-tonal-small-selected-outline-width`
`xlarge-selected-outline-width`	`0px` `--ct-icon-button-filled-xlarge-selected-outline-width`	`0px` `--ct-icon-button-outlined-xlarge-selected-outline-width`	`0px` `--ct-icon-button-standard-xlarge-selected-outline-width`	`0px` `--ct-icon-button-tonal-xlarge-selected-outline-width`
`xsmall-selected-outline-width`	`0px` `--ct-icon-button-filled-xsmall-selected-outline-width`	`0px` `--ct-icon-button-outlined-xsmall-selected-outline-width`	`0px` `--ct-icon-button-standard-xsmall-selected-outline-width`	`0px` `--ct-icon-button-tonal-xsmall-selected-outline-width`

Size⁠

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

Name	`extra-small`	`small`	`medium`	`large`	`extra-large`
`container-height`	`32px` `--ct-icon-button-xsmall-container-height`	`40px` `--ct-icon-button-small-container-height`	`56px` `--ct-icon-button-medium-container-height`	`96px` `--ct-icon-button-large-container-height`	`136px` `--ct-icon-button-xlarge-container-height`
`corner-end-end-radius`	same as `corner-radius` `--ct-icon-button-xsmall-corner-end-end-radius`	same as `corner-radius` `--ct-icon-button-small-corner-end-end-radius`	same as `corner-radius` `--ct-icon-button-medium-corner-end-end-radius`	same as `corner-radius` `--ct-icon-button-large-corner-end-end-radius`	same as `corner-radius` `--ct-icon-button-xlarge-corner-end-end-radius`
`corner-end-start-radius`	same as `corner-radius` `--ct-icon-button-xsmall-corner-end-start-radius`	same as `corner-radius` `--ct-icon-button-small-corner-end-start-radius`	same as `corner-radius` `--ct-icon-button-medium-corner-end-start-radius`	same as `corner-radius` `--ct-icon-button-large-corner-end-start-radius`	same as `corner-radius` `--ct-icon-button-xlarge-corner-end-start-radius`
`corner-radius`	`--ct-sys-corner-radius-full` `--ct-icon-button-xsmall-corner-radius`	`--ct-sys-corner-radius-full` `--ct-icon-button-small-corner-radius`	`--ct-sys-corner-radius-full` `--ct-icon-button-medium-corner-radius`	`--ct-sys-corner-radius-full` `--ct-icon-button-large-corner-radius`	`--ct-sys-corner-radius-full` `--ct-icon-button-xlarge-corner-radius`
`corner-start-end-radius`	same as `corner-radius` `--ct-icon-button-xsmall-corner-start-end-radius`	same as `corner-radius` `--ct-icon-button-small-corner-start-end-radius`	same as `corner-radius` `--ct-icon-button-medium-corner-start-end-radius`	same as `corner-radius` `--ct-icon-button-large-corner-start-end-radius`	same as `corner-radius` `--ct-icon-button-xlarge-corner-start-end-radius`
`corner-start-start-radius`	same as `corner-radius` `--ct-icon-button-xsmall-corner-start-start-radius`	same as `corner-radius` `--ct-icon-button-small-corner-start-start-radius`	same as `corner-radius` `--ct-icon-button-medium-corner-start-start-radius`	same as `corner-radius` `--ct-icon-button-large-corner-start-start-radius`	same as `corner-radius` `--ct-icon-button-xlarge-corner-start-start-radius`
`icon-size`	`20px` `--ct-icon-button-xsmall-icon-size`	`24px` `--ct-icon-button-small-icon-size`	`24px` `--ct-icon-button-medium-icon-size`	`32px` `--ct-icon-button-large-icon-size`	`40px` `--ct-icon-button-xlarge-icon-size`
`selected-corner-end-end-radius`	same as `selected-corner-radius` `--ct-icon-button-xsmall-selected-corner-end-end-radius`	same as `selected-corner-radius` `--ct-icon-button-small-selected-corner-end-end-radius`	same as `selected-corner-radius` `--ct-icon-button-medium-selected-corner-end-end-radius`	same as `selected-corner-radius` `--ct-icon-button-large-selected-corner-end-end-radius`	same as `selected-corner-radius` `--ct-icon-button-xlarge-selected-corner-end-end-radius`
`selected-corner-end-start-radius`	same as `selected-corner-radius` `--ct-icon-button-xsmall-selected-corner-end-start-radius`	same as `selected-corner-radius` `--ct-icon-button-small-selected-corner-end-start-radius`	same as `selected-corner-radius` `--ct-icon-button-medium-selected-corner-end-start-radius`	same as `selected-corner-radius` `--ct-icon-button-large-selected-corner-end-start-radius`	same as `selected-corner-radius` `--ct-icon-button-xlarge-selected-corner-end-start-radius`
`selected-corner-radius`	`--ct-sys-corner-radius-medium` `--ct-icon-button-xsmall-selected-corner-radius`	`--ct-sys-corner-radius-medium` `--ct-icon-button-small-selected-corner-radius`	`--ct-sys-corner-radius-large` `--ct-icon-button-medium-selected-corner-radius`	`--ct-sys-corner-radius-extra-large` `--ct-icon-button-large-selected-corner-radius`	`--ct-sys-corner-radius-extra-large` `--ct-icon-button-xlarge-selected-corner-radius`
`selected-corner-start-end-radius`	same as `selected-corner-radius` `--ct-icon-button-xsmall-selected-corner-start-end-radius`	same as `selected-corner-radius` `--ct-icon-button-small-selected-corner-start-end-radius`	same as `selected-corner-radius` `--ct-icon-button-medium-selected-corner-start-end-radius`	same as `selected-corner-radius` `--ct-icon-button-large-selected-corner-start-end-radius`	same as `selected-corner-radius` `--ct-icon-button-xlarge-selected-corner-start-end-radius`
`selected-corner-start-start-radius`	same as `selected-corner-radius` `--ct-icon-button-xsmall-selected-corner-start-start-radius`	same as `selected-corner-radius` `--ct-icon-button-small-selected-corner-start-start-radius`	same as `selected-corner-radius` `--ct-icon-button-medium-selected-corner-start-start-radius`	same as `selected-corner-radius` `--ct-icon-button-large-selected-corner-start-start-radius`	same as `selected-corner-radius` `--ct-icon-button-xlarge-selected-corner-start-start-radius`
`pressed-corner-end-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-xsmall-pressed-corner-end-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-small-pressed-corner-end-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-medium-pressed-corner-end-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-large-pressed-corner-end-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-xlarge-pressed-corner-end-end-radius`
`pressed-corner-end-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-xsmall-pressed-corner-end-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-small-pressed-corner-end-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-medium-pressed-corner-end-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-large-pressed-corner-end-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-xlarge-pressed-corner-end-start-radius`
`pressed-corner-radius`	`--ct-sys-corner-radius-small` `--ct-icon-button-xsmall-pressed-corner-radius`	`--ct-sys-corner-radius-small` `--ct-icon-button-small-pressed-corner-radius`	`--ct-sys-corner-radius-medium` `--ct-icon-button-medium-pressed-corner-radius`	`--ct-sys-corner-radius-large` `--ct-icon-button-large-pressed-corner-radius`	`--ct-sys-corner-radius-large` `--ct-icon-button-xlarge-pressed-corner-radius`
`pressed-corner-start-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-xsmall-pressed-corner-start-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-small-pressed-corner-start-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-medium-pressed-corner-start-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-large-pressed-corner-start-end-radius`	same as `pressed-corner-radius` `--ct-icon-button-xlarge-pressed-corner-start-end-radius`
`pressed-corner-start-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-xsmall-pressed-corner-start-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-small-pressed-corner-start-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-medium-pressed-corner-start-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-large-pressed-corner-start-start-radius`	same as `pressed-corner-radius` `--ct-icon-button-xlarge-pressed-corner-start-start-radius`
`narrow-leading-space`	`4px` `--ct-icon-button-xsmall-narrow-leading-space`	`4px` `--ct-icon-button-small-narrow-leading-space`	`12px` `--ct-icon-button-medium-narrow-leading-space`	`16px` `--ct-icon-button-large-narrow-leading-space`	`32px` `--ct-icon-button-xlarge-narrow-leading-space`
`narrow-trailing-space`	`4px` `--ct-icon-button-xsmall-narrow-trailing-space`	`4px` `--ct-icon-button-small-narrow-trailing-space`	`12px` `--ct-icon-button-medium-narrow-trailing-space`	`16px` `--ct-icon-button-large-narrow-trailing-space`	`32px` `--ct-icon-button-xlarge-narrow-trailing-space`
`regular-leading-space`	`6px` `--ct-icon-button-xsmall-regular-leading-space`	`8px` `--ct-icon-button-small-regular-leading-space`	`16px` `--ct-icon-button-medium-regular-leading-space`	`32px` `--ct-icon-button-large-regular-leading-space`	`48px` `--ct-icon-button-xlarge-regular-leading-space`
`regular-trailing-space`	`6px` `--ct-icon-button-xsmall-regular-trailing-space`	`8px` `--ct-icon-button-small-regular-trailing-space`	`16px` `--ct-icon-button-medium-regular-trailing-space`	`32px` `--ct-icon-button-large-regular-trailing-space`	`48px` `--ct-icon-button-xlarge-regular-trailing-space`
`wide-leading-space`	`10px` `--ct-icon-button-xsmall-wide-leading-space`	`14px` `--ct-icon-button-small-wide-leading-space`	`24px` `--ct-icon-button-medium-wide-leading-space`	`48px` `--ct-icon-button-large-wide-leading-space`	`72px` `--ct-icon-button-xlarge-wide-leading-space`
`wide-trailing-space`	`10px` `--ct-icon-button-xsmall-wide-trailing-space`	`14px` `--ct-icon-button-small-wide-trailing-space`	`24px` `--ct-icon-button-medium-wide-trailing-space`	`48px` `--ct-icon-button-large-wide-trailing-space`	`72px` `--ct-icon-button-xlarge-wide-trailing-space`

Other tokens⁠

These stay the same whatever the variant and size.

Token	Value
`--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-icon-button-icon-fill`	`1` `--ct-icon-button-icon-fill`
`--ct-icon-button-selected-icon-fill`	`1` `--ct-icon-button-selected-icon-fill`
`--ct-icon-button-unselected-icon-fill`	`0` `--ct-icon-button-unselected-icon-fill`

Names and states⁠

A toggle icon button has the role of a button and follows the WAI-ARIA Authoring Practices: Button pattern in its toggle form.

The accessible name is the aria-label, or the title when there is no aria-label. An icon from icon-name or selected-icon-name never names the button.
A slotted img or svg is not hidden. Give an img an empty alt, or an svg aria-hidden, when aria-label already names the action.
Only aria-label, aria-haspopup, and aria-expanded take effect. Any other aria-* attribute has no effect.
A screen reader announces the button as pressed or not pressed, tracking selected.
With disabled, a screen reader announces the button as unavailable.
The tooltip text is the button's description: a screen reader reads it after the name, and skips it when it only repeats the name. It never names the button.
A badge adds nothing to the name or description. When a count matters, put it in aria-label.
selected-aria-label replaces aria-label while selected, and only when aria-label is also set. The pattern lets the pressed state carry the change, so set it only when the new name is clearer.

Keyboard and focus⁠

Key	Action
Tab	Moves focus to the button, and away from it.
Enter	Toggles `selected` when pressed, and again on each repeat while the key is held.
Space	Toggles `selected` once, when released.

Space does not scroll the page and Enter does not submit a form. Moving focus away before Space is released cancels the toggle.

A focus ring shows on keyboard focus only, and hides on pointer down.
disabled removes the button from the Tab order.
soft-disabled keeps it in the Tab order with aria-disabled="true". Both keys and a click do nothing.

Pointer and touch⁠

touch-target offers none, overflow, and wrapper. The touch target is at least 48 by 48 pixels, and the default overflow extends it past the painted size.
That meets WCAG 2.5.8, which asks for 24 by 24 pixels, unless none is set at a size under 24 pixels.
Size shows the settings.

Display settings⁠

Forced colors: the button takes a 1px ButtonText border with the button's own corners. A selected toggle takes ActiveText, and a disabled button a dashed GrayText border. Hover and press draw a 2px and a 4px ButtonText border, and the focus ring is a solid CanvasText outline.
Reduced motion: the press ripple, the focus-ring animation, and the tooltip fade are skipped. The corner morph on press completes instantly.
Right to left: only icons set with icon-name and selected-icon-name mirror, and only with flip-icon-in-rtl and flip-selected-icon-in-rtl. A slotted icon is never mirrored.

Standards⁠

With its defaults, the toggle icon 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 an aria-label.
2.5.3 Label in Name (A): keep any visible text's words in the aria-label.
2.4.6 Headings and Labels (AA): write an aria-label that says what the setting does.
1.1.1 Non-text Content (A): give a slotted image an empty alt, or mark a slotted svg decorative.

Toggle icon button

Reference docs⁠link

Choosing a button⁠link

Choosing a variant⁠link

Built in⁠link

Using them well⁠link

Variants⁠link

Size⁠link

Icons⁠link

Badges⁠link

Tooltips⁠link

Names⁠link

Forms⁠link

Disabled and soft-disabled⁠link

Properties⁠link

Slots⁠link

Events⁠link

Props⁠link

Children⁠link

Events⁠link

Parameters⁠link

Render fragments⁠link

Event callbacks⁠link

Inputs⁠link

Content projection⁠link

Outputs⁠link

Props⁠link

Slots⁠link

Events⁠link

Props⁠link

Snippets⁠link

Events⁠link

Variant⁠link

Size⁠link

Other tokens⁠link

Names and states⁠link

Keyboard and focus⁠link

Pointer and touch⁠link

Display settings⁠link

Standards⁠link

Reference docs⁠

Choosing a button⁠

Choosing a variant⁠

Built in⁠

Using them well⁠

Variants⁠

Size⁠

Icons⁠

Badges⁠

Tooltips⁠

Names⁠

Forms⁠

Disabled and soft-disabled⁠

Properties⁠

Slots⁠

Events⁠

Props⁠

Children⁠

Events⁠

Parameters⁠

Render fragments⁠

Event callbacks⁠

Inputs⁠

Content projection⁠

Outputs⁠

Props⁠

Slots⁠

Events⁠

Props⁠

Snippets⁠

Events⁠

Variant⁠

Size⁠

Other tokens⁠

Names and states⁠

Keyboard and focus⁠

Pointer and touch⁠

Display settings⁠

Standards⁠