A tooltip is a short descriptive message that appears when a user hovers or focuses on an element.

Standard tooltip

Tooltip with utility classes

<h3 class="site-preview-heading">Standard tooltip</h3>
<div class="padding-8">
  <div class="margin-4">
    <button type="button" class="usa-button usa-tooltip" data-position="top" title="Top">Show on top</button>
  <div class="margin-4">
    <button type="button" class="usa-button usa-tooltip" data-position="right" title="Right">Show on right</button>
  <div class="margin-4">
    <button type="button" class="usa-button usa-tooltip" data-position="left" title="Left">Show on left</button>
  <div class="margin-4">
    <button type="button" class="usa-button usa-tooltip" data-position="bottom" title="Bottom">Show on bottom</button>

<h3 class="site-preview-heading">Tooltip with utility classes</h3>
<div class="grid-row padding-8">
  <div class="tablet:grid-col-3 margin-top-2 text-center">
    <button type="button" class="usa-button usa-tooltip" data-position="top" data-classes="width-full tablet:width-auto" title="Top">Show on top</button>
  <div class="tablet:grid-col-3 margin-top-2 text-center">
    <button type="button" class="usa-button usa-tooltip" data-position="bottom" data-classes="width-full tablet:width-auto" title="Bottom">Show on bottom</button>
  <div class="tablet:grid-col-3 margin-top-2 text-center">
    <button type="button" class="usa-button usa-tooltip" data-position="right" data-classes="width-full tablet:width-auto" title="Right">Show on right</button>
  <div class="tablet:grid-col-3 margin-top-2 text-center">
    <button type="button" class="usa-button usa-tooltip" data-position="left" data-classes="width-full tablet:width-auto" title="Left">Show on left</button>


When to use the tooltip component

  • 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.
  • Hed. Be careful not introduce conflicting hover or focus events.
  • Hed. If using tooltips in one context, use in all similar contexts.
  • Hed. Use the data-position attribute to prevent the tooltip from covering other page elements.


  • 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 the tooltip component

  • 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.

Tooltip settings

This component has no settings.

Tooltip variants

This component has no variants.


  • Package usage: @import usa-tooltip
  • Requires: required, global