Skip to main content

Tooltip

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


Default Tooltip

Component Preview



Component Code

<button class="usa-button usa-tooltip" data-position="top" title="This is a tooltip">
  Hover or focus to see tooltip
</button>

Tooltip on Icon

Component Preview

Information

Component Code

<span class="usa-tooltip" data-position="top" title="More information available">
  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
    <use xlink:href="/civic-guide/uswds/img/sprite.svg#info"></use>
  </svg>
  <span class="usa-sr-only">Information</span>
</span>

Tooltip Positions

Component Preview


Component Code

<!-- Top position (default) -->
<button class="usa-button usa-tooltip" data-position="top" title="Tooltip on top">
  Top
</button>

<!-- Bottom position -->
<button class="usa-button usa-tooltip" data-position="bottom" title="Tooltip on bottom">
  Bottom
</button>

<!-- Left position -->
<button class="usa-button usa-tooltip" data-position="left" title="Tooltip on left">
  Left
</button>

<!-- Right position -->
<button class="usa-button usa-tooltip" data-position="right" title="Tooltip on right">
  Right
</button>


Guidance

When to use the tooltip component

To provide supplementary information that isn't essential but may be helpful to some users.
To label icons or icon-only buttons that don't have visible text.
To define abbreviations or acronyms on first use.

When to consider something else

If the information is critical to completing a task.
Critical information should always be visible on the page, not hidden in a tooltip.
If the tooltip content is lengthy or complex.
Consider using a modal, expandable content, or inline help text instead.
If users need to interact with the tooltip content.
Tooltips disappear on mouse out, so users can't click links or copy text within them. Use a popover or modal instead.

Usability guidance

Keep tooltip text short and concise.
Tooltips are meant for brief, supplementary information. Aim for one sentence or less.
Don't hide essential information in tooltips.
Information necessary to complete a task should be visible on the page without requiring user interaction.
Position tooltips to avoid covering important content.
Use the appropriate position attribute (top, bottom, left, right) to ensure the tooltip doesn't obscure related content.
Avoid using tooltips on mobile touch devices.
Hover interactions don't work well on touch screens. Consider alternative approaches for mobile users.

Accessibility guidance

Tooltips must be keyboard accessible.
The USWDS tooltip component displays on both hover and focus, ensuring keyboard users can access the information.
Use the title attribute for tooltip content.
The tooltip component reads from the title attribute to populate the tooltip text, which provides a native fallback.
Provide screen reader text for icon-only triggers.
When using tooltips on icons, include a usa-sr-only span with descriptive text for screen reader users.
Don't rely solely on color to convey meaning.
If the tooltip trigger conveys status or importance, ensure this information is also available through text or icons.

USWDS Documentation

For more guidance, view the USWDS Tooltip Component Documentation.



Settings

Variable Description
$theme-tooltip-background-color

Background color of the tooltip.
$theme-tooltip-font-color

Text color of the tooltip.
$theme-tooltip-font-size

Font size of the tooltip text.


Variants

Variant Description

data-position="top"

Displays the tooltip above the trigger element. This is the default position.

data-position="bottom"

Displays the tooltip below the trigger element.

data-position="left"

Displays the tooltip to the left of the trigger element.

data-position="right"

Displays the tooltip to the right of the trigger element.
Looking for U.S. government information and services?
Visit USA.gov