IconButton

Square (or round) button holding a single icon and no text. Reach for it in dense or space-constrained spots — toolbars, table rows, input adornments, card headers — where a recognizable glyph reads faster than a label. If the action needs words to be understood, use Button instead (or pair this with a Tooltip); the icon alone carries no text for screen readers, so always set aria-label. It shares Button’s variant + tone API: primary / default for the main or standalone action, outline for a bordered secondary action, and ghost / link for the quiet, chromeless ones that sit inside toolbars and rows. The tone prop colors primary / outline / link for destructive, success, or accent (lilac) intent. Sizes are sm (28px, dense rows and inline use), md (32px, the default for standalone and form rows), and lg (36px, hero/presence) — matching the shared control scale so it lines up with a Button in the same row.

Variants

<>
  <IconButton variant="primary" aria-label="Add"><Plus /></IconButton>
  <IconButton variant="default" aria-label="Add"><Plus /></IconButton>
  <IconButton variant="outline" aria-label="Add"><Plus /></IconButton>
  <IconButton variant="ghost" aria-label="Add"><Plus /></IconButton>
  <IconButton variant="link" aria-label="Add"><Plus /></IconButton>
</>

Sizes

<>
  <IconButton size="sm" aria-label="Search"><Search /></IconButton>
  <IconButton size="md" aria-label="Search"><Search /></IconButton>
  <IconButton size="lg" aria-label="Search"><Search /></IconButton>
</>

Round (circle)

<>
  <IconButton round aria-label="Add"><Plus /></IconButton>
  <IconButton variant="default" round aria-label="Search"><Search /></IconButton>
  <IconButton variant="outline" round aria-label="Search"><Search /></IconButton>
</>

Destructive tone

<>
  <IconButton variant="primary" tone="destructive" aria-label="Delete"><X /></IconButton>
  <IconButton variant="outline" tone="destructive" aria-label="Delete"><X /></IconButton>
</>

Accent tone (lilac)

<>
  <IconButton variant="primary" tone="accent" aria-label="Add"><Plus /></IconButton>
  <IconButton variant="outline" tone="accent" aria-label="Add"><Plus /></IconButton>
</>

States

<>
  <IconButton aria-label="Normal"><Plus /></IconButton>
  <IconButton disabled aria-label="Disabled"><Plus /></IconButton>
  <IconButton loading aria-label="Saving"><Plus /></IconButton>
</>

Props

Prop	Type	Default
variant	"primary" \| "default" \| "outline" \| "ghost" \| "link"	"primary"
tone	"default" \| "destructive" \| "success" \| "accent"	"default"
size	"sm" \| "md" \| "lg"	"md"
loading	boolean	false
disabled	boolean	false
asChild	boolean	false
aria-label	string (required)	—

Source

packages/react/src/components/icon-button.tsx · Figma node 2718:8839