Components

Tooltip

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

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

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