Icon Button

Icon Buttons trigger actions using a single icon with no visible label. Use them when space is constrained or the action is universally understood. They share the same variants and visual language as Button and always require an accessible label.

preview

props

PropTypeDefaultDescription
childrenReactNoderequiredThe icon element to render inside the button.
aria-labelstringrequiredAccessible name — required because there is no visible text label.
variant"primary" | "secondary" | "secondary-neutral" | "ghost""primary"Visual style of the button.
size"large" | "medium" | "small""medium"Dimensions of the button.
destructivebooleanfalseApplies red colour treatment to primary and secondary variants.
disabledbooleanfalsePrevents interaction and reduces opacity.
onClick() => void—Called when the button is pressed.

usage

Use icon buttons when space is tight and the icon alone communicates the action clearly. Always pair with an aria-label — never rely on a tooltip as a substitute for an accessible name.

When to use

  • Toolbars and action rows where labels would crowd the layout
  • Universally recognised actions — edit, delete, close, search

Do not use

  • When the action needs a label to be understood — use a regular Button instead
  • As the sole affordance for a critical action where clarity is essential
DoUse for universally understood actions in dense layouts
Don’tUse when the action requires a label to be understood

variants

PrimaryThe default. For the most important action in a group.
SecondaryFor supporting actions that complement a primary action.
Secondary NeutralA tonal variant for use on light or neutral surfaces.
GhostLow-emphasis. For inline, supplementary, or subtly destructive actions.

size

LargeFor prominent actions and spacious layouts. 56×56px.
MediumStandard size for most layouts. 48×48px.
SmallCompact, for dense toolbars and tight spaces. 32×32px.

states

DefaultResting state
HoverDarkened background on cursor over
FocusFocus ring shown on keyboard navigation only