Components

Icon Button

A square button that holds a single icon. Shares the same variant and color system as Button — filled, outlined, ghost × brand, neutral, destructive, and more. aria-label is required.

Variants & colors

Icon Button uses the same variant × color matrix as Button. Ghost neutral is the default — the right choice for toolbar and row actions where you want low visual noise.

ghost · neutral (default)

ghost · brand

outlined · brand

filled · brand

ghost · destructive

Sizes

Matches Button heights exactly so Icon Buttons can sit inline with text buttons without misalignment.

sm · 32px

md · 40px

lg · 48px

Disabled state

In context — row actions

The most common pattern: a tight cluster of sm ghost icon buttons at the end of a list row. The destructive action (delete) uses color="destructive" to add weight without needing a label.

Untitled component
Button — primary
Card — elevated

Anatomy

ContainerSquare <button> element. Width and height are set by the size prop.
IconPassed as the icon prop. Should be an SVG with aria-hidden="true". Scale the SVG viewBox to match the size (16/18/20px).
aria-labelRequired. The visible text equivalent — announced by screen readers in place of a visible label.

Size reference

sm32 × 32px16pxTable rows, compact toolbars, side panels.
md40 × 40px18pxDefault. Most standalone icon button contexts.
lg48 × 48px20pxTouch targets, hero-level actions.

Keyboard & accessibility

Space / EnterActivates the button.
TabMoves focus to/from the button.
aria-labelRequired. Provides the accessible name. Screen readers announce it instead of icon content.
aria-hiddenSet on the icon SVG. Prevents double-announcement of graphical content.
TooltipWrap in Tooltip with the same text as aria-label so sighted users can discover the action on hover.

Usage guidance

DoAlways set aria-label. An icon-only button with no accessible name is a critical accessibility failure.
DoWrap Icon Button in Tooltip using the same string as aria-label — sighted users need discoverability too.
DoUse ghost neutral for toolbar and list-row actions. Reserve filled/outlined for primary or persistent actions.
DoUse color="destructive" for delete/remove/clear actions even in ghost variant — it adds intent without a label.
Don'tUse Icon Button if the action isn't universally understood from the icon alone. Add a text label instead.
Don'tMix sizes within a single toolbar or button group.

Tokens used

action/primaryBrand filled background, ghost/outlined color
action/primary-hoverBrand hover state
action/primary-disabledFilled disabled background
action/on-primaryIcon color on filled brand button
action/neutralGhost neutral icon color (default)
action/neutral-hoverGhost neutral hover icon color
action/destructiveDestructive variant icon color
action/destructive-hoverDestructive hover icon color
bg/faintGhost variant hover background tint
text/disabledDisabled icon color
border/disabledOutlined disabled border
border-width/baseOutlined border (1px)
radius/mdsm size corner radius
radius/lgmd and lg size corner radius
Figma: In progressReact: v1