Icon Button
Last Updated: September 2026Icon buttons are compact, iconography only button alternative best used for compact UIs or when a collection of actions must always be quickly accessible. They come in a variety of styles and sizes to support clear hierarchy when constructing a UI.
Source CodeAnatomy
link- 1Container
- 2Icon
Variants
linkDefault
Neutral surface. Default for most toolbar and table actions.
Subtle Accent
Low-emphasis accent tint for supportive accent actions.
Strong Accent
High-emphasis accent fill for a prominent icon action.
Subtle Danger
Low-emphasis destructive tint for removable or discard actions.
Strong Danger
High-emphasis destructive fill — confirm irreversible actions first.
Sizes
linkIcon buttons support 4 sizes: XS, S, M, and L.
Usage Guidelines
linkWhen to use
- •For compact, icon-only actions in toolbars, tables, and dense layouts.
- •When a text label would clutter the UI and the icon meaning is unmistakable.
- •As secondary actions next to a primary labeled Button.
When not to use
- •When the action needs a visible text label — use Button instead.
- •For the primary call-to-action in a view — prefer a labeled Button or FAB.
Always provide an accessible name with aria-label.
Don't omit aria-label — icon-only buttons need an accessible name.
Use widely recognized icons that match the action.
Don't rely on obscure icons for critical or destructive actions.
Behaviors
linkLoading state
- •Set loading=true to replace the icon with a Spinner and disable interaction.
- •Keep the same size so the toolbar layout does not shift.
Disabled state
- •Set disabled=true to prevent interaction.
- •Disabled IconButtons are not focusable.
Content Guidelines
linkAccessible names
- •Write aria-label as a short verb phrase ('Edit patient', 'Delete draft').
- •Match the label to what the action does, not the icon name.
Icon choice
- •Prefer standard Material Symbols for common actions (edit, delete, add, more_vert).
- •Keep icons consistent across the product for the same action.
Accessibility
linkText & Labels
- •IconButton has no visible text — aria-label (or aria-labelledby) is required.
- •Tooltip text should match the accessible name when a tooltip is present.
ARIA attributes
- •aria-label provides the accessible name.
- •aria-disabled communicates disabled state when using non-native disable patterns.
Keyboard Support
- •Tab → focus the button.
- •Space / Enter → activate.
WCAG Compliance Standards
FAQs
linkWhen should I use IconButton instead of Button?
Use IconButton when the action is icon-only. Use Button when you need a visible text label, with or without an icon.
Can IconButton show a label?
No — children are not supported. Use Button with an icon prop when you need text.
How do I handle async actions?
Set loading=true while the request is in flight. The control disables itself and shows a spinner.