The tooltip behavior is implemented in our React API and is not part of the Vanilla API.
Icon Button
Button component for actions represented purely by an icon.
Use Icon Button...
- For universally understood actions such as Close and Search.
- When space is limited.
Don't use Icon Button...
- Perform a primary or critical action, like Submit or Checkout.
- Convey an ambiguous actions.
- When there is enough space to use labelled Buttons.
The preview has been updated.
Tooltip
The Icon Button tooltip is a short, non-interactive text label, its purpose is to provide the accessible name and a clear description of an Icon button's function.
If users need to provide a more detailed or slightly different accessible label for screen reader users, they can pass aria-label or aria-labelledby along with the tooltip. In this case, the Tooltip will serve only as the visual label, while ARIA attributes will provide the accessible name.
The preview has been updated.
Skins
Secondary
Use skin="secondary" for all Buttons by default. Multiple secondary actions can be displayed on a page.
The preview has been updated.
Primary
Use skin="primary" for the main action of the page.
- Use a single ‘primary’ Icon Button on a page only when it is the main call-to-action and does not compete with a primary Button.
The preview has been updated.
Tertiary
Use skin="tertiary" when a more subtle Icon Button is required.
The preview has been updated.
Destructive Primary
Use skin="destructive-primary" if an action will destroy data, usually within a confirmation Modal Dialog.
Refer to the Destructive Actions pattern for more information.
The preview has been updated.
Destructive Secondary
Use skin="destructive-secondary" to indicate an action will destroy data. This action would usually trigger a Modal Dialog confirming the destruction of data.
Refer to the Destructive Actions pattern for more information.
The preview has been updated.
Destructive Tertiary
Use skin="destructive-tertiary" when a more subtle Icon Button is required. This action would usually trigger a Modal Dialog confirming the destruction of data.
Refer to the Destructive Actions pattern for more information.
The preview has been updated.
Disabled
Use disabled when an Icon Button’s action is unavailable. Refer to guidelines.
The preview has been updated.
Loading
Use the loading state to indicate that an action is in progress. The Icon Button will render a Spinner to visually indicate the loading state.
For assistive technologies, the visual updates must be accompanied by an ARIA live region on your page (not as a descendant of Button) to announce changes even when the Icon Button is not in focus. Do not render this live region conditionally as it can lead to announcement issues. Instead render the text inside the live region conditionally. An example can be seen below:
The preview has been updated.
The preview has been updated.
Content
- Choose an icon that is semantically aligned with its action. For instance, use the 'edit' icon only for editing actions and a 'delete' icon for deleting actions.
- The IconButton component uses a required tooltip prop to provide a visual label on hover or focus.
- The tooltip content should be short and succinct, with a recommended character max. count 45 to avoid wrapping and to stay within the 250px maximum width.
- Avoid overriding the icon sizes or icon color, Icon Button handles this automatically for visual consistency.
Do
Write a short, descriptive label that explains the Icon Button's action.
Dont
Rely on the Tooltip to communicate critical information.
Dont
Use icons that are not widely recognized or could have multiple meanings.
Icon Button vs. Button
Use Icon Button...
- To save space, ideal for dense layouts like toolbars, lists or mobile.
- To communicate a concise, well-known action.
- For instantly recognizable actions like search, or edit.
Use Button...
- Primary actions, CTAs, complex, critical or unique actions.
- The Button's purpose is not immediately clear from its surrounding.
Tooltip Behavior
- Tooltip appears on hover and focus.
- Tooltip hides immediately when a mousedown event is triggered on the button.
- Tooltip is not shown for disabled buttons.
Icon skin and size
- Icons inside Icon Button have a fixed
standardsize. Applying thesizeprop on theIconcomponent will not change the size. - The
skinprop on theIconcomponent is also ignored when used inside an IconButton. - Destructive Icon Button skins automatically apply the appropriate destructive icon styling.
Placement
- Place Icon Buttons in flow near relevant content. Use negative space to ensure the icon action stands out.
- Group Icon Buttons consistently with other content-related Icon Buttons to create a clean and predictable user experience. e.g. group ‘right text alignment’ next to other text alignment options.
Disabled
- Disabling Icon Buttons can confuse users since they afford little feedback. Users may not understand why the button cannot be clicked and may be blocked from progressing through the flow. It is often better to allow an Icon Button to be clicked, then communicate to the user what is blocking them from progressing.
- If an Icon Button is disabled, its tooltip will not be shown. This prevents users from getting conflicting feedback.
Accessibility
- Icon Button uses the
tooltipprop as its accessible name by default. This ensures the button always has an accessible name, even if no additional props are provided. However, if the tooltip text is too short or doesn’t fully describe the action, you can provide a more descriptive name usingaria-labeloraria-labelledby. This helps screen reader users understand the button’s exact purpose. - Make sure the Icon Button is accessible via keyboard navigation and can be activated with the Enter or Space keys.
Props
IconButton
This component is implemented using the
<button /> as the root element. You can utilize the native attributes supported by <button /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.See core props for additional props that can be applied to this component.
| prop | type | required | description | default |
|---|---|---|---|---|
| aria-label | string | false | Defines a string value that labels the current element.
Accessible name for screen readers.
If omitted, the tooltip will populate aria-label.
Use this to provide a more descriptive or alternative name for assistive technologies.
@see aria-labelledby. | null |
| aria-labelledby | string | false | Identifies the element (or elements) that labels the current element.
ID reference to an element that provides an accessible name for the button, used by assistive technologies.
If provided, screen readers will read the referenced element's content as the button's accessible name.
@see aria-describedby. | null |
| skin | "primary" | "secondary" | "tertiary" | "destructive-primary" | "destructive-secondary" | "destructive-tertiary" | false | The visual style of the Button | secondary |
| loading | boolean | false | Activates the loading state.
Should be used with a separate live region to provide updates to screen readers. | null |
| tooltip | string | true | Visual label shown on hover/focus. | null |
How does Icon Button meet your needs?
Related