IconButton
IconButton is a Button that holds a single icon, with uniform padding and a circular
shape. It shares Button's colors, variants and sizes. It has no visible text, so always pass label.Actions
When to use
Use when
- The action is recognizable by its icon alone — close, expand, settings, favorite.
- Space is tight: toolbars, app bars, table rows, card headers.
Avoid when
Usage
loadingGhost clusters
variant="ghost" shows only the glyph at rest and a circular wash on hover, focus and press. Use it for groups of
chrome actions. A linked IconButton gets the same wash instead of an underline.
<IconButton variant="ghost" size="small" icon={<Icon icon={cog} />} label="Settings" />
<IconButton variant="ghost" size="small" icon={<Icon icon={thumbsUp} />} label="Like" />Sizes
size takes extraSmall, small, medium (default) or large. Every size is circular except extraSmall, which
keeps a small radius so tiny glyphs do not look squashed.
<IconButton icon={<Icon icon={cog} />} size="extraSmall" label="Settings" />
<IconButton icon={<Icon icon={cog} />} size="large" label="Settings" />While isLoading is true the icon is replaced by a Spinner, or by loadingComponent when you pass one.
Accessibility
- Renders a native
<button>; Enter and Space activate it. WhileisLoading, it reportsaria-busy, stays focusable and ignores clicks. labelbecomes thearia-label. Without it the button has no accessible name. A nativearia-labelyou pass directly takes precedence.- Under forced colors (Windows High Contrast), the focus outline is restored with the system
Highlightcolor.
Properties
Name
Type
Default
Description
color"primary""secondary""tertiary""success""warning""danger""neutral"'primary'Semantic color of the button.
containmentstringnoneContainment marker for the `cq` channel: emits
`container-type` (+ `container-name` when the string form carries one,
e.g. `'inline-size card'`). Apply on the immediate wrapper of the
adapting component — NEVER on page-level shells.
iconReactNodenoneIcon displayed next to the text. Accepts any `ReactNode`, but the
typical usage is with the `<Icon />` component.
@example ```tsx
<Button icon={<Icon icon={trash} />} text="Delete" />
```
iconPosition"left""right"'left'Position of the icon relative to the text.
isLoadingbooleanfalseReplaces the content with a spinner while true. The button width is
preserved to avoid reflow during the transition.
Named `isLoading` (rather than `loading`) because `loading` is a native
`<button>` attribute.
labelstringnoneAccessible name of the button, rendered as `aria-label` — required for
screen readers since the button has no visible text.
@example ```tsx
<IconButton icon={<Icon icon={trash} />} label="Delete item" />
```
legibility"on-photo"noneReading-shadow preset for text over a photographic background
(`on-photo`). Replaces the inline `style={{ textShadow }}` in the
consumer (brasil_2030 radar, gap A3). Token emission is deferred until a
2nd consumer asks for the raw var (see backlog).
lineClampnumbernoneCaps the text at this many lines and ends the cut with an ellipsis.
The full string stays in the DOM.
loadingComponentReactNodenoneComponent displayed in place of the icon when `isLoading` is true.
When omitted, the default `Spinner` is used.
pageShellbooleannoneCenters the element and caps the width at `theme.layout.pageMaxWidth`.
The page shell of a classic centered layout.
readablenumberbooleannoneMakes the `color` legible against the page surface: `true` = WCAG AA
(4.5), a number sets a custom floor. Ignored with `contrast`.
See the Layout Props concept page for the full semantics.
size"small""medium""large""extraSmall"'medium'Size of the button.
textstringnoneText to display. Alternative to passing content via `children` — when
both are provided, `children` takes precedence.
transformstringnoneCSS `transform` value (e.g. `translate(-50%, -33px)`). Never leaks
to the DOM as an attribute.
variant"contained""outlined""linked""ghost"'contained'Visual variant.