Tooltip

Tooltips add additional context to interactive UI elements and appear on mouse hover or keyboard focus.

Page navigation navigation

Reserve Tooltips to visually surface the label for IconButtons.
Keep the Tooltip text minimal.
Never include Tooltips on non-interactive components (div, span, p) because it will not be accessible for keyboard or screen reader users.

Best practices

IconButtons with Tooltips for edit, favorite, and sponsor — Use a Tooltip on an IconButton to help convey the purpose of the action

Don’t

Non-interactive text element activating a long and wordy Tooltip on hover — Don't use Tooltips on non-interactive elements

IconButtons have a visually hidden label utilizing aria-label. To instead display that label in a Tooltip, the label option should be used. The label serves as the accessible name for the control utilitizing aria-labelledby under the hood.

The description is intended to supplement the control's text label by utilitizing aria-describedby under the hood, and will be announced to a screen reader in addition to the label. Keep the description short and concise.

IconButton with Tooltip as a description

IconButtons have a visually hidden label utilizing aria-label. To provide context in addition to the visually hidden label, use the description option.

Button with visible label

Button labeled Notifications with Tooltip as a description

For buttons that have a visible label, the description option can also be used to provide additional context.

Alternatives to Tooltips

Before adding a Tooltip, please consider: Is this information essential and necessary? Can the UI be made clearer? Can the information be shown on the page by default? See Tooltip alternatives for more accessible alternatives.

We use aria-label for Tooltip contents. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content.

A Tooltip may only be used on an element that is interactive such as a button or a link. Even if an element is focusable, a Tooltip may only be used if the element does something when it's clicked.

1. Persist the content

If possible, persist the content so it's always available rather than using a Tooltip, which hides content by default. This ensures that the content is always discovered and surfaced to users regardless of device.

Information about how many discussions can be pinned added to the confirmation dialog — Find an appropriate permanent place to display additional information.

Don’t

Information about how many discussions can be pinned within Tooltip on non-interactive element — Don't use a Tooltip to add additional helpful information

2. Don't duplicate content

If the Tooltip duplicates content that is already available on the page, remove it.

Pointer hovering over a link with no Tooltip — Remove any duplicate Tooltip text.

Don’t

Screenshot of Tooltip with GitHub username, @inkblotty, on a static span that says @inkblotty — Don't set Tooltips that duplicate the trigger element content.

Consider using a modal, which is accessible for mobile users and allows you to structure content that may otherwise be crammed into a Tooltip.

Screenshot of GitHub Actions page with a modal that conveys workflow file information about a runner — Do use a pattern that is accessible to a larger number of users such as a modal

Don’t

Screenshot of GitHub Actions page using a Tooltip on a static element to convey long workflow file information — Don't place long content inside a Tooltip

4. Use a summary disclosure

Consider using a summary disclosure that is accessible for mobile users and also offers the ability to show or hide content.

Screenshot of GitHub pricing page that uses a summary disclosure to hide and show additional information on each point — Do use a pattern that is accessible to a larger number of users such as a summary disclosure

Don’t

Other

If you are unsure which alternative is more suited to your scenario and need help, consult a designer or the GitHub Accessibility team (if you are GitHub staff) for advice.