Anatomy
- Icon: The graphical symbol that represents the action or function
Usage Guidelines
Buttons fall under different roles based on the priority level of the actions they trigger. Each of the below variants are associated with a button role.
Choose the button role based on the priority level of the call to action.
When to use this component
- For frequent actions in space-constrained UI like navigation bars, toolbars, and headers where icons clearly communicate intent
- As primary or secondary actions when the icon is universally recognizable (e.g., search, share, close, edit, delete).
- In repeated UI patterns like lists or cards where consistent iconography helps users quickly scan and interact with multiple items.
When not to use this component
- When space allows for labeled buttons. Prefer buttons with text labels when layout permits, as they're clearer and more accessible.
- For ambiguous or uncommon actions where users might not understand the icon's meaning without a label
- In critical onboarding flows where first-time users need extra clarity. Use Button instead.
-
For complex actions that benefit from descriptive text labels to reduce cognitive load.
Best Practices
Use icon buttons in space-constrained areas where labeled buttons don't fit
Don't use unclear or decorative icons that obscure the action's purpose
Use primary variant for the most important action in each context
Don't use multiple primary variants in the same context.
Prioritize essential actions and hide less important ones in overflow menus
Don't overload interface with too many visible icon buttons.
Ensure consistent sizing within the same group of buttons
Don't mix sizes within the same group of related actions. Use different roles for hierarchy.
Use the danger role only for actions that have destructive outcomes, such as deletion.
Don't use the danger role for non-destructive actions, such as saving, or adding.
States
There exist three different states for tabs:
- Default: The standard style when the Button is available for interaction
- Pressed: Brief visual indication when the button is being pressed
- Focused: Visual indicator (focus ring) when the button receives focus
Where's the disabled button?
We have made the conscious decision to not provide a disabled button for now. We firmly believe that most of the solutions that use a disabled button can be solved in many other simpler ways, for instance, by using validation, progressive disclosure, or lowering the actions per page to reduce the cognitive load. We enforce this for a few reasons:
- Using disabled buttons makes us wonder why the button is not available and how to enable it. This requires explicit explanation and therefore increases the complexity of the screen (we cannot just forbid the action and not explain what is happening).
- Showing disabled buttons when they cannot be enabled in any way is frustrating. It clutters the interface and confuses us since a solution is not possible.
- Accessibility. It’s also a silent agreement that a disabled button has a very poor contrast. Disabled buttons could additionally be confused with secondary or plain buttons and just make the whole experience only accessible to the ones that can see the difference.
Variants
Sizes
Icon Button come in 2 distinct heights.
Small
Use this size for lower-priority actions in tight spaces. Use it inline within content, such as next to text or embedded in lists and cards, where the button needs to be less prominent than the surrounding content.
Medium (default)
This is the standard size for the majority of actions, ensuring a comfortable tap target and prominence on the screen. Use it in toolbars, headers, navigation bars, and other structural UI elements.
Styles
Plain variant customization
The icon color can be modified to integrate with surrounding content while maintaining required accessibility contrast ratios.
Known Gaps
- Accessibility Guidelines
- To have disabled states or not to have disabled states