When to Use
Example: app top bar (back, title, icon actions)
- Compact action triggers in toolbars, table rows, or card headers where space is limited
- Common icon-recognizable actions like close, delete, edit, or share
- Always provide
aria-label— the icon alone is not accessible without a text alternative - If the action needs a text label for clarity, use a standard Button with an icon instead
Usage Guidelines
DO
Always provide aria-label — Icon Button has no visible text. Use consistent icon styles within a toolbar
Don’t
Don't use Icon Button when text would improve clarity. Don't omit the aria-label — it is required
Interaction Behavior
Three Shapes
| Shape | Radius | Use Case |
|---|---|---|
| rounded | 999px (full circle) | Floating action buttons (FAB), primary icon actions |
| square | 16px | Toolbars, card actions |
| rectangle | 24px + wider horizontally | Horizontal layouts, pill shape |
Three Fill Styles
| Style | Appearance | Use Case |
|---|---|---|
| filled | Colored background + white icon | Primary actions, high priority |
| outline | Transparent background + colored border + colored icon | Secondary actions |
| ghost | No background, no border + colored icon | Low-interference actions, toolbars |
Accessibility
Icon Button has no visible text — an aria-label is required:
<IconButton icon={<SearchIcon />} aria-label="Search" />| Requirement | Details |
|---|---|
aria-label | Required, describes the button action |
| Focus ring | 2px brand-pink focus ring on keyboard focus |
| Contrast | Icon-to-background contrast ≥ 4.5:1 |