Icon button

Usage

Use an icon button when the purpose of your button may be easily understood using an icon in place of a text label.

Best practices

• Verify that the button's purpose will still be understood using an icon without a text label. Consider your audience and the context where the button is being rendered.
• Use a tooltip with a text label for the button so users can hover or focus the button to read a button label that makes it clear what the button does.

Options

Icon buttons have the same size and variant options as a button with a text label.

Accessibility and usability expectations

Even though the label is visually hidden, a text label needs to be defined so a screen reader can read that label to the user. A graphical IconButton must:

1. Have an accessible name (acting as a text alternative for the Octicon) that describes the action that will be performed when the button is activated.
2. Be visually recognisable as representing the action. For example, a magnifying glass icon could be used to represent a search button, with a text alternative of "Search". This allows voice control software users to activate the button by saying "click search", whereas an icon that wasn't recognisable as representing the text alternative would leave the user guessing at the button's accessible name, and other users guessing at its purpose.

Built-in accessibility features

By default, this component is rendered as a regular <button> with a nested <svg> for the Octicon. The aria-label property is used as the button's accessible name.

<button … aria-label="…">
  <svg aria-hidden="true" …> … </svg>
</button>

When the disabled property is set, the component is rendered as a standard <button disabled> … </button> disabled button.

When the inactive property is set, the component is rendered as <button aria-disabled="true"> … </button> – the control itself is visually styled to appear disabled. However, the control is still keyboard-focusable, and can still be activated.

The selectable variant/scheme colors meet minimum color contrast requirements.

The size variants all meet the minimum target size requirement.

In the Rails implementation, IconButton automatically has a visible tooltip that appears when the button is hovered and when it receives keyboard focus. The tooltip visually replicates the accessible name of the button. The tooltip can be hovered when using the mouse, and can be dismissed using Esc without needing to move the mouse or focus away from the button.

Implementation requirements

Accessible name

You must provide a sufficiently descriptive aria-label for the component.

Target size

The button must have a minimum target size of 24×24 CSS pixels. This is to ensure that the button is large enough to be easily activated by users with motor impairments.

Convey meaning with more than color

IconButton has different schemes/variants (such as default, danger, invisible), which result in different colors for the icon, background, and borders. These differences are purely visual, so they may be difficult to distinguish for users with impaired color perception. They also won't be perceived by screen reader users. For this reason, you can't rely on the scheme/variant alone to give meaning to your buttons.

Make sure to differentiate icon buttons through the use of sufficiently different Octicons, rather than their visual presentation.

How to test the component

Integration tests

• The button has a sufficiently descriptive accessible name
• The button uses an icon with sufficiently clear meaning that conveys its action
• If the button uses a schema/variant for a particular presentation, the button does not solely rely on this visual aspect to convey its purpose, or to differentiate it from other buttons

Component tests

• The aria-label added to the component is output as the button's aria-label
• Unless the button is disabled, it can be focused and activated using the keyboard
• If the button is set to be inactive, it still receives keyboard focus, but it conveys its inactive/disabled state to screen readers with the aria-disabled="true" attribute
• The button has a minimum target size of 24×24 CSS pixels, regardless of content
• For the Rails implementation, the tooltip for the button can be hovered with the mouse, and the tooltip can be dismissed using Esc without needing to move the mouse or focus away from the button

Known accessibility issues (GitHub staff only)

Related links

• Button usage
• Button