Components

Tooltip

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

Passed WCAG 2.1 AA

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>
  <div class="margin-4">
    <button
      type="button"
      class="usa-button usa-tooltip"
      data-position="right"
      title="Right"
    >
      Show on right
    </button>
  </div>
  <div class="margin-4">
    <button
      type="button"
      class="usa-button usa-tooltip"
      data-position="left"
      title="Left"
    >
      Show on left
    </button>
  </div>
  <div class="margin-4">
    <button
      type="button"
      class="usa-button usa-tooltip"
      data-position="bottom"
      title="Bottom"
    >
      Show on bottom
    </button>
  </div>
</div>

<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>
  <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>
  <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>
  <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>
  </div>
</div>

<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>
  <div class="margin-4">
    <button
      type="button"
      class="usa-button usa-tooltip"
      data-position="right"
      title="Right"
    >
      Show on right
    </button>
  </div>
  <div class="margin-4">
    <button
      type="button"
      class="usa-button usa-tooltip"
      data-position="left"
      title="Left"
    >
      Show on left
    </button>
  </div>
  <div class="margin-4">
    <button
      type="button"
      class="usa-button usa-tooltip"
      data-position="bottom"
      title="Bottom"
    >
      Show on bottom
    </button>
  </div>
</div>

<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>
  <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>
  <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>
  <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>
  </div>
</div>

Guidance

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

Test the tooltip component in your own project.

USWDS tested the tooltip component for accessibility. You should test your implementation, too.

Use tooltip accessibility tests

• 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

Variable	Description
$theme-tooltip-background-color	Background color of tooltip.
$theme-tooltip-font-color	Text color of tooltip.
$theme-tooltip-font-size	Font size of tooltip.

Tooltip variants

This component has no variants.

Accessibility test status

The USWDS team did 13 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:

Total tests	Passed	Passed with exceptions	Conditional	Failed
13	12	0	0	1

Overview of recent accessibility test results:

• Passed: 12
• Passed with exceptions: 0
• Conditional: 0
• Failed: 1

Learn more on the tooltip accessibility tests page.

Package

• Package usage: @forward "usa-tooltip";
• Dependencies: uswds-fonts

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date	USWDS version	Affects	Breaking	Description
2024-06-07	N/A	Guidance	No	Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2646
2024-05-31	3.8.1	Accessibility JavaScript	No	Updated component behavior to close active tooltips when the escape key is pressed. This allows the component to meet the “dismissible” standard outlined in WCAG 1.4.13. More information: uswds#5909
2024-05-31	3.8.1	Accessibility JavaScript Styles	No	Updated component behavior to allow users to hover over tooltip content. This allows the component to meet the “hoverable” standard outlined in WCAG 1.4.13. More information: uswds#5919
2023-09-29	3.6.1	Styles	No	Restored the opacity: 0 style rule to the tooltip’s initial state. This prevents the component from flickering if its position needs to be recalculated. More information: uswds#5475
2023-06-09	3.5.0	JavaScript	No	Fixed a bug that removed default positioning. If the data-position attribute is not specified, the tooltip position will now default to “top”. More information: uswds#5228
2022-10-19	3.2.0	JavaScript	No	Updated tooltip to allow for dynamic initialization. Tooltip initializes on first interaction and checks if component has been initialized before toggling. If it hasn’t initialized properly it will call a setup attributes function. More information: uswds#4955
2022-04-28	3.0.0	Assets JavaScript Styles	Breaking	Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656
2021-11-01	2.12.2	JavaScript	No	Added automatic sanitizing. The design system now automatically sanitizes content in elements we compose with JavaScript. This means that components like combo box, tooltip, file input, and date picker will sanitize any content passed to them. This helps protect any design system implementation against malicious XSS attacks through these components. More information: uswds#4329
2021-03-17	2.11.0	JavaScript Styles	No	Fixed tooltip positioning. We fixed an issue that prevented some longer tooltips in some positions to display incorrectly. More information: uswds#4062