Tooltip – Design

Anatomy

The Tooltip consists of three primary elements that work together to add quick clarity to an element.

Tooltip background, content
Caret
Trigger

Options

The Tooltip supports the following configurations to accommodate various supplementary information scenarios.

Content

Text content

By default, Tooltips support a basic string of text, with only minimal additions that can be added, such as emojis.

Custom content

Content within the Tooltip can be customized beyond text, but only with non-interactive elements.

Placement

Tooltip placement adjusts automatically when insufficient space is available. See behaviors for details.

Visual States

Tooltips open when the trigger element is in a hover or focus state. Avoid removing opening on focus, as this prevents keyboard-only users from viewing Tooltips.

A Tooltip appearing on both the hover and focus state of a Button.

Behavior

The Tooltip responds to space constraints with automatic positioning adjustments and overflow handling.

Overflow handling

Text in a Tooltip will wrap. The max-width of a Tooltip is 272px or 17rem, while the text region is 256px or 16rem.

Usage Guidelines

Standard	Requirement
DoSupplementary information for interactive elements	Use the Tooltip as supplementary information for interactive elements on the page.
DoDescribe Button Icons	The meaning behind icons is usually not universally understood. Adding a Tooltip can support the understanding of a Button Icon.
DoUse under space constraints	When space is constrained, use Tooltips for supplemental information such as definitions and contextual help. Consider inline text as an alternative in most cases.
DoUse for informational overlays	Tooltip is the component of choice for tips and other informational overlays. Use a Popover in place of a Tooltip when actions are needed.
DoPosition to avoid screen edges and obstruction	When elements are placed toward a screen edge, position Tooltips to open in the opposite direction, and position them to minimize obstruction of important elements. When neither consideration applies, use the top position as the default placement.
DoApply only to keyboard-accessible elements	For a Tooltip to be accessible by keyboard and screen readers, the element it is tied to must be keyboard accessible, typically some form of button or link.
Don’tUse for error messaging	Avoid using Tooltips for error messaging. Use inline error messages or Field Message components instead.
Don’tUse for critical information	Information essential to the completion of the task should be visible on the page, not only in a Tooltip.
Don’tApply to disabled elements	Avoid adding Tooltips to disabled elements. Disabled elements are not keyboard accessible. Add the Tooltip information on the page itself, or provide a dedicated help Button Icon.
Don’tAdd interactive elements	Tooltips should not have interactive elements. If an overlay needs interactive elements, use the Popover instead; see Tooltip vs Popover. For other interactive elements, add this information on the page itself, or provide a dedicated help Button Icon.

Alternatives

Tooltips are generally difficult to both discover and use on the page, particularly for touch device users. Explore alternatives to a Tooltip first, such as inline text. Tooltip is the component of choice for tips and other informational overlays. Popovers may be used in place of a Tooltip when actions are needed.

Usage	Tooltip	Popover
Can have a link?	Should not have interactive elements	Yes
Can have other interactive elements?	Should not have interactive elements	Yes
Open mechanic?	Hover or Focus	Click/Press, option for Hover or Focus
Can trap user focus?	No	Yes

Content

Content within the Tooltip should be brief, clear, and supplementary to the trigger element.

Keep content 1-2 lines

When content extends to 3+ lines, it is strongly encouraged to find another method of conveying the information.

Don’t

Don’t repeat the content of the Tooltip’s trigger

Avoid repeating the trigger’s content in the Tooltip, even in UIs that heavily use Tooltips. Omitting a redundant Tooltip is preferred over consistent Tooltip usage in the UI.

Don’t

Keyboard Interaction

Users can navigate the Tooltip using standard keyboard controls.

Key	Description
Tab	When focusing on the trigger, activates the Tooltip
Escape	Hides the Tooltip

Accessibility

Anvil provides accessibility needs out of the box. Annotating labels is the main piece needed in a design. Provide a label to describe the action for both screen readers and users who focus on the element, regardless of whether a label is visible on the page. For more guidance on labels and context, see input field context association best practices.

Anvil2 Web

Resources

Tooltip – Design

Anatomy

Options

Content

Text content

Custom content

Placement

Visual States

Behavior

Overflow handling

Usage Guidelines

Alternatives

Tooltip vs Popover

Content

Keep content 1-2 lines

Don’t repeat the content of the Tooltip’s trigger

Keyboard Interaction

Accessibility

Provide Tooltip labels for Icon Buttons

​Anatomy

​Options

​Content

​Text content

​Custom content

​Placement

​Visual States

​Behavior

​Overflow handling

​Usage Guidelines

​Alternatives

​Tooltip vs Popover

​Content

​Keep content 1-2 lines

​Don’t repeat the content of the Tooltip’s trigger

​Keyboard Interaction

​Accessibility

​Provide Tooltip labels for Icon Buttons

Anatomy

Options

Content

Text content

Custom content

Placement

Visual States

Behavior

Overflow handling

Usage Guidelines

Alternatives

Tooltip vs Popover

Content

Keep content 1-2 lines

Don’t repeat the content of the Tooltip’s trigger

Keyboard Interaction

Accessibility

Provide Tooltip labels for Icon Buttons