Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System

Tooltip

Tooltips provide additional information upon hover, focus or click. The information should be contextual, useful, and nonessential information.

Examples

The Tooltip component can render a variety of content ranging from short descriptive text, to paragraphs with links, or more complex interactive popovers.

The component provides a variety of props to configure tooltip behavior for these different use cases (i.e. interactive, dialog), and to customize styling (i.e. offset, maxWidth, className). The element that triggers a Tooltip can also be fully customized via props (i.e. triggerComponent, triggerContent).

This component makes use of @popperjs/core for tooltip positioning, focus-trap-react for trapping focus in Tooltip Dialogs, and react-transition-group for animations.

Icon Trigger

Loading

Inline

Loading

Interactive content

Loading

With Close

Loading

Code

React

React Properties Documentation
NameTypeDefaultDescription
activeClassNamestringClasses applied to the tooltip trigger when the tooltip is active
ariaLabelstringHelpful description of the tooltip for screenreaders
childrenrequiredReactNodeTooltip trigger content
classNamestringClasses applied to the tooltip trigger
closeButtonLabelstringConfigurable text for the aria-label of the tooltip's close button
componentanybuttonWhen provided, will render the passed in component for the tooltip trigger. Typically will be a button, a, or rarely an input element.
contentHeadingReactNodeHeading for the tooltip content. This will show above 'title' content and inline with 'closeButton' if closeButton is set
dialogbooleanTooltip that behaves like a dialog, i.e. a tooltip that only appears on click, traps focus, and contains interactive content. For more information, see Deque's tooltip dialog documentation
idstringid applied to tooltip body container element. If not provided, a unique id will be automatically generated and used.
interactiveBordernumber15Sets the size of the invisible border around interactive tooltips that prevents it from immediately hiding when the cursor leaves the tooltip.
inversedboolean
offset[number, number][0, 5]Applies skidding and distance offsets to the tooltip relative to the trigger. See the popperjs docs for more info.
onClose() => anyCalled when the tooltip is hidden
onOpen() => anyCalled when the tooltip is shown
placementPlacementtopPlacement of the tooltip body relative to the trigger. See the popperjs docs for more info.
maxWidthstring300pxmaxWidth styling applied to the tooltip body
showCloseButtonbooleanDetermines if close button is shown in tooltip. It is recommended that the close button is only used if dialog=true
titlerequiredReactNodeContent inside the tooltip body or popover. If contains interactive elements use the dialog prop.
transitionDurationnumber250Duration of the react-transition-group CSSTransition. See the timeout option for more info.
zIndexnumber9999zIndex styling applied to the tooltip body

<TooltipIcon> component

When using the <TooltipIcon> as the only child of <Tooltip>, be sure to provide an aria-label on the <Tooltip> to ensure an accessible name for the trigger.

React Properties Documentation
NameTypeDefaultDescription
inversedbooleanIf true sets inverse fill color.
classNamestringAdditional CSS classes to be added to the svg element
ariaHiddenbooleanDescribes the value of the aria-hidden attribute on the SVG. Defaulted to true with the assumption that most icons are decorative. If the icon does not have any associated label text, set this to false and ensure a title is provided for improved accessibility.
idstringA custom id attribute for the SVG
titlestringThe descriptive name for the SVG icon
viewBoxstringA string describing the viewbox of the SVG. It is recommended that the icon is centered and fill up the default viewport size. See this blog post for further explanation on viewBox and how to use it.
descriptionstringLong-text description of any SVG. Use for complex icons, otherwise title prop will suffice.

Styles

The following CSS variables can be overridden to customize Tooltip fields:

CSS variables for tooltip
VariableDefault Core Theme Value
--tooltip__background-colorhex value: #ffffff--color-white
--tooltip__border-colorhex value: #404040--color-gray-darker
--tooltip__border-color--active#0071bc40
--tooltip__border-color--inverse-activehex value: #ffffff40--color-transparent-white-alpha25
--tooltip__border-width1px
--tooltip__colorhex value: #262626--color-base
--tooltip__box-shadow-colorhex value: #a6a6a6--color-gray-light
--tooltip-icon__colorhex value: #0071bc--color-primary
--tooltip-icon__color--inversehex value: #ffffff--color-white
--tooltip-trigger__colorhex value: #0071bc--color-primary

Guidance

When to use

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

When to consider alternatives

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

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Not applicable

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete