Tooltip

When to use

• Helpful, non-critical information. Use tooltips to strengthen an existing message.
• Enhance confidence. Use tooltips to increase certainty about an interaction.
• Brief descriptions. Tooltips perform best with succinct helper text.
• Lack of space. Tooltips are useful as a last resort for space-constrained UI. Explore other options for keeping content visible without a tooltip.

When to consider something else 

• Critical information. Don’t hide information necessary for completing a task behind an tooltip interaction.
• Lengthy descriptions. Tooltips are microcopy, and should be brief. Don’t use a tooltip if you need a lot of text.
• Redundant content. Don’t use a tooltip when its content is repetitive or if usability is obvious.
• Sufficient space. If content can fit outside a tooltip, don’t use a tooltip.

Usability guidance

• Use affordances. A hidden tooltip is unusable. Use tooltips only on elements that appear interactive, like buttons or links.
• Avoid collisions. Be careful not introduce conflicting hover or focus events.
• Use consistently. If using tooltips in one context, use in all similar contexts.
• Don’t block content. Use the data-position attribute to prevent the tooltip from covering other page elements.

Accessibility guidance 

• Use as title attribute. Tooltips are progressive enhancements for the title attribute, and will display as the title attribute if the component doesn’t initialize.
• Keyboard accessibility. Tooltips make title attributes keyboard accessible.

Using tooltips - NEEDS TO BE CUSTOMIZED

• Any element with the class name usa-tooltip and a title attribute will become a tooltip.
• Place tooltips on elements with as few child elements as possible.
• Elements or text that show a tooltip when hovered or focused will not wrap onto a new line and will get tabindex="0" for keyboard interaction.
• By default, tooltips appear on the top of their related element.
• Use the data-position attribute to indicate the tooltip’s position in relation to the related element:
  • data-position="top": On top, horizontally centered. If the data-position attribute is omitted, the tooltip will appear on top by default.
  • data-position="bottom": Below, horizontally centered
  • data-position="right": To the right, vertically centered
  • data-position="left": To the left, vertically centered
• Tooltips are protected from viewport clipping. If clipping is detected, the tooltip is positioned on the opposite side as data-position attribute indicates. If the tooltip is still clipped, it is positioned on top of the element, with its width constrained to the width its related element. Only then does the tooltip wrap to multiple lines.
• JavaScript generated most of the tooltip’s markup. Apply utility classes to any tooltip’s wrapping element, by including them inside a data-classes attribute, separated by spaces.