Icon button

An icon button runs an action shown by one icon alone, such as close, share, or more, where space is tight. Its variants set how much attention the action draws, so play stands out and shuffle stays quiet. A built-in badge counts what is waiting, with no element for you to place. Try the player, app bar, and composer below, and watch the inbox badge come and go.

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 an icon button draws, from most to least:

Filled: the one icon action a group most needs, such as play in a media bar or send in a compose area.
Tonal: an important action beside a filled one, such as pause or edit.
Outlined: a secondary action that still needs a visible edge, such as bookmark or share on a card.
Standard: the quietest action, a bare icon for dense rows, such as more, close, or back in an app bar.

Built in⁠

badge-value or badge-dot puts a badge on the icon, and badge-concealed hides it and restores it with its count.
A plain tooltip from tooltip-value, opening on hover and on keyboard focus, with no separate element to place.
A touch target at least 48 by 48 pixels at every size, even where the icon button paints smaller (touch-target).
Form submission: type submits the icon button's form or resets it, and a submit sends name with value.
A link, from href, that keeps the icon button's shape and colors.
A soft-disabled state, soft-disabled, that stops the action and keeps the icon button in the Tab order.

Using icon buttons well⁠

Show an action by an icon alone only when the icon is widely recognized; give an action that needs words to a button.
Give every icon button an accessible name with aria-label, in the words a sighted reader takes from the icon.
Place icon buttons in toolbars, app bars, and other compact layouts, and use one to open a menu or a search.
Keep one filled icon button in a group, and make its neighbors tonal, outlined, or standard.

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

Variants⁠

Set variant to one of the four variants; Choosing a variant says when each one fits. Omit it and the icon button takes the variant from your style configuration, which is filled unless you have changed it.

Give every icon button an aria-label, because the icon alone gives it no accessible name.

Size and width⁠

size sets the icon button's height and icon size, from extra-small to extra-large. Omit it and the icon button takes the size from your style configuration, which is small unless you have changed it.

width makes the container narrow or wide around the same icon; the style configuration's default is regular. Use a wide icon button where a row has room and the action deserves a larger target, and a narrow one where icon buttons sit tightly side by side.

touch-target decides how the touch area of at least 48 by 48 pixels meets your layout. The style configuration's default, overflow, lets it extend past a smaller button without taking layout space; wrapper makes the icon button take that space; and none shrinks the touch area to the visible button.

Icons⁠

Name a Material Symbols icon in icon-name, or put an icon element such as a cw-icon in the default slot. When both are set, the slotted icon wins and the icon button logs a warning.

On a right-to-left page, flip-icon-in-rtl mirrors an icon-name icon, so a back or forward arrow points the way the page reads. A slotted icon is never mirrored.

Badges⁠

badge-value puts a short count or label on the icon, and badge-dot shows a small dot with no text instead. badge-concealed hides the badge and keeps its value, so clearing it shows the same badge again.

The demo repeats the count in the aria-label, for the reason Names and states gives.

Tooltips⁠

tooltip-value shows a tooltip on hover and on keyboard focus, which is how a sighted reader learns what an icon means. tooltip-position places it; the style configuration's default is end-center.

A tooltip showing the icon button's name, as in the first demo, is the common case; Names and states says what a screen reader makes of it.

title shows the browser's own tooltip instead; prefer tooltip-value, which also opens on keyboard focus.

Links⁠

href makes the icon button a link: a screen reader announces it as one, and a click follows the address. target chooses where it opens; the preview refuses a new tab, so the demo keeps to a jump within itself.

Set aria-label on every link icon button; title does not name a link.

Forms⁠

Inside a form, an icon button submits it: type is submit unless you set it. Set type to reset to reset the form, or to button for an action that leaves the form alone, such as a toolbar's. name and value add a pair to the submitted data, so a form can tell two submit buttons apart.

The preview does not submit forms, so the demo shows each click from on:click; on your page the form submits.

Disabled and soft-disabled⁠

disabled turns an action off completely: the icon button leaves the Tab order and cannot be activated. soft-disabled turns it off and keeps it in the Tab order, so a keyboard or screen reader user can still reach it and hear its tooltip. Use soft-disabled when the reader should find the action and learn why it is unavailable.

A soft-disabled icon button swallows its click, so the demo's status line changes only once the actions are back on.

In a compact layout⁠

Icon buttons earn their place where a label would not fit: the actions on a message, a card, or a row in a list. Each one keeps its own Tab stop, so give each an aria-label that says what it does to this item, and set type to button when the row sits inside a form.

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.
`download`	`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipIconInRtl`	`flip-icon-in-rtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`form`read-only		`HTMLFormElement`	The form the component belongs to, or `null` when it has none.
`href`	`href`	`string`	The URL that the link icon button points to. When set, the icon button is a link: a screen reader announces it as one, and a click follows the URL instead of submitting or resetting its form. A disabled or soft-disabled link icon button cannot be followed. See Links.
`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 the element's value is submitted under with its form. See Forms.
`rel`	`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`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 and width.
`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.
`target`	`target_blank`, `_self`, `_parent`, `_top`, `""`	`UrlTargetUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where a link icon button opens `href`. It has no effect without `href`. Empty, the link opens in the same tab. See Links.
`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, Links.
`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 and width.
`type`	`typebutton`, `reset`, `submit`	`FormSubmitterBehaviorFormSubmitterBehavior.Button`, `.Reset`, `.Submit`default `FormSubmitterBehavior.Submit`	What a click does to the icon button's form: `submit` submits it, `reset` resets it, and `button` does nothing. It has no effect on a link icon button or outside a form. See Forms, In a compact layout.
`value`	`value`	`string`	The value added to a form with the button's name when the button submits a form. See Forms.
`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 and width.

With href set, the icon button is a link and takes no part in its form: type, name, and value are ignored.

Slots⁠

Slot	Description
(default)	The icon: a `cw-icon` or an inline `svg`. It overrides `iconName`, and the icon button logs a warning when both are set. Text alone renders nothing.

Events⁠

Event	Type	Detail	Description
`link-activate`	`LinkActivateEvent`	`LinkActivateEventDetail`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable.
`click`	`MouseEvent`	—	Dispatched when the icon button is clicked. A disabled or soft-disabled one does not dispatch it. It bubbles, is composed, and is cancelable.

A click that a listener cancels with preventDefault() neither submits nor resets the form.

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.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`form`read-only (ref)	`HTMLFormElement`	The form the component belongs to, or `null` when it has none.
`href`	`string`	The URL that the link icon button points to. When set, the icon button is a link: a screen reader announces it as one, and a click follows the URL instead of submitting or resetting its form. A disabled or soft-disabled link icon button cannot be followed. See Links.
`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 the element's value is submitted under with its form. See Forms.
`onNavigate`	`(detail: LinkActivateEventDetail, event: LinkActivateEvent) => void`	Called when the link points inside the app: the same origin, opening in the same tab. The browser's navigation is canceled first, so this handler navigates, and it replaces the navigation `ChameleonRouterProvider` would make.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`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 and width.
`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.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where a link icon button opens `href`. It has no effect without `href`. Empty, the link opens in the same tab. See Links.
`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, Links.
`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 and width.
`type`	`FormSubmitterBehaviorTypeFormSubmitterBehavior.Button`, `.Reset`, `.Submit`default `FormSubmitterBehavior.Submit`	What a click does to the icon button's form: `submit` submits it, `reset` resets it, and `button` does nothing. It has no effect on a link icon button or outside a form. See Forms, In a compact layout.
`value`	`string`	The value added to a form with the button's name when the button submits a form. See Forms.
`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 and width.

With href set, the icon button is a link and takes no part in its form: type, name, and value are ignored.

Children⁠

Child	Description
`children`	The icon: a `CrIcon` or an inline `svg`. It overrides `iconName`, and the icon button logs a warning when both are set. Text alone renders nothing.

Events⁠

Prop	Argument	Description
`onLinkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`onClick`	`React.MouseEvent<HTMLElement>`	Dispatched when the icon button is clicked. A disabled or soft-disabled one does not dispatch it. It bubbles, is composed, and is cancelable.

A click that a listener cancels with preventDefault() neither submits nor resets the form.

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.
`Download`	`string?`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `Href` is set.
`FlipIconInRtl`	`bool?`default `false`	Mirrors the `IconName` icon when the text direction is right to left. See Icons.
`Href`	`string?`	The URL that the link icon button points to. When set, the icon button is a link: a screen reader announces it as one, and a click follows the URL instead of submitting or resetting its form. A disabled or soft-disabled link icon button cannot be followed. See Links.
`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 the element's value is submitted under with its form. See Forms.
`OnNavigate`	`EventCallback<LinkActivateEventArgs>`	Navigates for a link that points inside the app: the same base address, opening in the same tab. The browser's navigation is canceled first, and this callback replaces the NavigationManager.NavigateTo the component calls by default. It is not called for any other link.
`Rel`	`string?`	The link's relationship to the linked URL, as the anchor's `Rel`, used exactly as given. Unset, the anchor has no `Rel`. Ignored unless `Href` is set.
`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 and width.
`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.
`Target`	`UrlTarget?UrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where a link icon button opens `Href`. It has no effect without `Href`. Empty, the link opens in the same tab. See Links.
`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, Links.
`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 and width.
`Type`	`FormSubmitterBehavior?FormSubmitterBehavior.Button`, `.Reset`, `.Submit`default `FormSubmitterBehavior.Submit`	What a click does to the icon button's form: `submit` submits it, `reset` resets it, and `button` does nothing. It has no effect on a link icon button or outside a form. See Forms, In a compact layout.
`Value`	`string?`	The value added to a form with the button's name when the button submits a form. See Forms.
`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 and width.

With href set, the icon button is a link and takes no part in its form: type, name, and value are ignored.

Render fragments⁠

Parameter	Type	Description
`ChildContent`	`RenderFragment?`	The icon: a `CbIcon` or an inline `svg`. It overrides `IconName`, and the icon button logs a warning when both are set. Text alone renders nothing.

Event callbacks⁠

Parameter	Type	Description
`OnLinkActivate`	`EventCallback<LinkActivateEventArgs>`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `Href`, `Target`, `Download`, `Rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`OnClick`	`EventCallback<MouseEventArgs>`	Dispatched when the icon button is clicked. A disabled or soft-disabled one does not dispatch it. It bubbles, is composed, and is cancelable.

A click that a listener cancels with preventDefault() neither submits nor resets the form.

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.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`href`	`string`	The URL that the link icon button points to. When set, the icon button is a link: a screen reader announces it as one, and a click follows the URL instead of submitting or resetting its form. A disabled or soft-disabled link icon button cannot be followed. See Links.
`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 the element's value is submitted under with its form. See Forms.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`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 and width.
`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.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where a link icon button opens `href`. It has no effect without `href`. Empty, the link opens in the same tab. See Links.
`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, Links.
`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 and width.
`type`	`FormSubmitterBehaviorTypeFormSubmitterBehavior.Button`, `.Reset`, `.Submit`default `FormSubmitterBehavior.Submit`	What a click does to the icon button's form: `submit` submits it, `reset` resets it, and `button` does nothing. It has no effect on a link icon button or outside a form. See Forms, In a compact layout.
`value`	`string`	The value added to a form with the button's name when the button submits a form. See Forms.
`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 and width.

With href set, the icon button is a link and takes no part in its form: type, name, and value are ignored.

Content projection⁠

Content	Description
content with no `slot`	The icon: a `CaIcon` or an inline `svg`. It overrides `iconName`, and the icon button logs a warning when both are set. Text alone renders nothing.

Outputs⁠

Output	Event	Description
`cwLinkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`cwClick`	`MouseEvent`	Dispatched when the icon button is clicked. A disabled or soft-disabled one does not dispatch it. It bubbles, is composed, and is cancelable.

A click that a listener cancels with preventDefault() neither submits nor resets the form.

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.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`href`	`string`	The URL that the link icon button points to. When set, the icon button is a link: a screen reader announces it as one, and a click follows the URL instead of submitting or resetting its form. A disabled or soft-disabled link icon button cannot be followed. See Links.
`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 the element's value is submitted under with its form. See Forms.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`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 and width.
`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.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where a link icon button opens `href`. It has no effect without `href`. Empty, the link opens in the same tab. See Links.
`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, Links.
`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 and width.
`type`	`FormSubmitterBehaviorTypeFormSubmitterBehavior.Button`, `.Reset`, `.Submit`default `FormSubmitterBehavior.Submit`	What a click does to the icon button's form: `submit` submits it, `reset` resets it, and `button` does nothing. It has no effect on a link icon button or outside a form. See Forms, In a compact layout.
`value`	`string`	The value added to a form with the button's name when the button submits a form. See Forms.
`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 and width.

With href set, the icon button is a link and takes no part in its form: type, name, and value are ignored.

Slots⁠

Slot	Description
`default`	The icon: a `CvIcon` or an inline `svg`. It overrides `iconName`, and the icon button logs a warning when both are set. Text alone renders nothing.

Events⁠

Event	Type	Description
`linkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`click`	`MouseEvent`	Dispatched when the icon button is clicked. A disabled or soft-disabled one does not dispatch it. It bubbles, is composed, and is cancelable.

A click that a listener cancels with preventDefault() neither submits nor resets the form.

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.
`download`	`string`	Downloads the linked URL instead of navigating to it. A file name saves it under that name, and an empty string downloads it under the server's own name, like the bare HTML attribute. Unset, it navigates. Ignored unless `href` is set.
`flipIconInRtl`	`boolean`default `false`	Mirrors the `iconName` icon when the text direction is right to left. See Icons.
`href`	`string`	The URL that the link icon button points to. When set, the icon button is a link: a screen reader announces it as one, and a click follows the URL instead of submitting or resetting its form. A disabled or soft-disabled link icon button cannot be followed. See Links.
`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 the element's value is submitted under with its form. See Forms.
`rel`	`string`	The link's relationship to the linked URL, as the anchor's `rel`, used exactly as given. Unset, the anchor has no `rel`. Ignored unless `href` is set.
`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 and width.
`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.
`target`	`UrlTargetTypeUrlTarget.Blank`, `.Self`, `.Parent`, `.Top`, `.Empty`default `UrlTarget.Empty`	Where a link icon button opens `href`. It has no effect without `href`. Empty, the link opens in the same tab. See Links.
`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, Links.
`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 and width.
`type`	`FormSubmitterBehaviorTypeFormSubmitterBehavior.Button`, `.Reset`, `.Submit`default `FormSubmitterBehavior.Submit`	What a click does to the icon button's form: `submit` submits it, `reset` resets it, and `button` does nothing. It has no effect on a link icon button or outside a form. See Forms, In a compact layout.
`value`	`string`	The value added to a form with the button's name when the button submits a form. See Forms.
`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 and width.

With href set, the icon button is a link and takes no part in its form: type, name, and value are ignored.

Snippets⁠

Snippet	Description
`children`	The icon: a `CsIcon` or an inline `svg`. It overrides `iconName`, and the icon button logs a warning when both are set. Text alone renders nothing.

Events⁠

Prop	Type	Description
`onLinkActivate`	`LinkActivateEvent`	Fired when the link is followed in the same tab, before the browser navigates. Cancel it to navigate with a router instead. It bubbles, is composed, and is cancelable. Its `detail` carries `href`, `target`, `download`, `rel`, `altKey`, `ctrlKey`, `metaKey`, `shiftKey`, and `originalEvent`.
`onClick`	`MouseEvent`	Dispatched when the icon button is clicked. A disabled or soft-disabled one does not dispatch it. It bubbles, is composed, and is cancelable.

A click that a listener cancels with preventDefault() neither submits nor resets the form.

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

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

Names and states⁠

An icon button follows the WAI-ARIA Authoring Practices: Button pattern; with href it is a link and follows the WAI-ARIA Authoring Practices: Link pattern.

An icon button has no accessible name of its own: a cw-icon is hidden from assistive technology, whether it comes from icon-name or the slot. Give every icon button an aria-label.
A slotted img or svg is not hidden. With no aria-label, its alt or <title> becomes the name.
title sets the browser's tooltip, and with no aria-label it is also the name. A link icon button takes its name from aria-label only.
On a button, only aria-label, aria-haspopup, and aria-expanded take effect. On a link icon button, only aria-label does. Any other ARIA attribute has no effect.
For an icon button that opens a menu, set aria-haspopup="menu"; keep aria-expanded in step with the menu. A disclosure takes aria-expanded alone.
soft-disabled makes a screen reader announce the icon button as unavailable, and a disabled or soft-disabled link icon button is still announced as a link, as unavailable, with no address.
The tooltip from tooltip-value is the icon button's description: a screen reader reads it after the name, and skips it when it only repeats the name. It never names the icon button.
An aria-label replaces the badge's count in the name. Put a count that matters into the aria-label too.
For an on/off setting, use a toggle icon button, which states its state with aria-pressed.

Keyboard and focus⁠

Key	Action
Tab	Moves focus to the icon button, then on to the next control.
Enter	Activates the icon button, or follows the link.
Space	Activates the icon button; a link icon button does not respond.
Escape	Hides the tooltip, when the icon button has one.

A focus ring shows on keyboard focus only, and hides on pointer down.
disabled takes the icon button out of the Tab order, so keyboard focus never reaches it or its tooltip.
soft-disabled keeps it in the Tab order. Enter and Space still fire a click, which the component swallows; a listener registered in the capture phase still sees it.

Pointer and touch⁠

The touch target is at least 48 by 48 pixels by default, reaching past the visible button (overflow), so every size meets 2.5.8 Target Size (Minimum), which asks for 24 by 24.
wrapper keeps the same area and makes the icon button take it in the layout; none shrinks it to the visible button (Size and width).
A disabled or soft-disabled icon button still takes hover; a soft-disabled one swallows the click.

Display settings⁠

Forced colors: the container gets a 1px ButtonText border with its own corners, and a disabled one a dashed GrayText border. Hover and press draw a ButtonText border, 2px and 4px, in place of the overlays, 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: only an icon-name icon with flip-icon-in-rtl mirrors. A slotted icon never does.

Standards⁠

With its defaults, an 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)

Five more depend on how you use it:

4.1.2 Name, Role, Value (A): give every icon button an aria-label.
2.5.3 Label in Name (A): keep the words a tooltip shows in the aria-label.
2.4.6 Headings and Labels (AA): write an aria-label that says what the action does.
1.1.1 Non-text Content (A): give a slotted image an alt, or name the icon button with aria-label and mark the image decorative.
2.4.4 Link Purpose (In Context) (A): label a link icon button with where it goes.

Icon button

Reference docs⁠link

Choosing a button⁠link

Choosing a variant⁠link

Built in⁠link

Using icon buttons well⁠link

Variants⁠link

Size and width⁠link

Icons⁠link

Badges⁠link

Tooltips⁠link

Links⁠link

Forms⁠link

Disabled and soft-disabled⁠link

In a compact layout⁠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 icon buttons well⁠

Variants⁠

Size and width⁠

Icons⁠

Badges⁠

Tooltips⁠

Links⁠

Forms⁠

Disabled and soft-disabled⁠

In a compact layout⁠

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⁠