Skip to main content
U.S. Flag

An official website of the United States government

CMS Design System


Warning: draft

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


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

View Source File

Code snippet


View Source File

Code snippet

Interactive content

View Source File

Code snippet

With Close

View Source File

Code snippet

Tooltip Props

React Properties Documentation

Classes applied to the tooltip trigger when the tooltip is active


Helpful description of the tooltip for screenreaders


Tooltip trigger content


Classes applied to the tooltip trigger


Configurable text for the aria-label of the tooltip's close button

componentReact.ReactElement<any> | any | ((...args: any[]) => any)'button'

When provided, will render the passed in component for the tooltip trigger. Typically will be a button, a, or rarely an input element.


Heading for the tooltip content. This will show above 'title' content and inline with 'closeButton' if closeButton is set


Tooltip 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


id applied to tooltip body container element. If not provided, a unique id will be automatically generated and used.


Sets the size of the invisible border around interactive tooltips that prevents it from immediately hiding when the cursor leaves the tooltip.

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() => any

Called when the tooltip is hidden

onOpen() => any

Called when the tooltip is shown


Placement of the tooltip body relative to the trigger. See the popperjs docs for more info.


maxWidth styling applied to the tooltip body


Determines if close button is shown in tooltip. It is recommended that the close button is only used if dialog=true


Content inside the tooltip body or popover. If contains interactive elements use the dialog prop.


Duration of the react-transition-group CSSTransition. See the timeout option for more info.


zIndex styling applied to the tooltip body


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.

View Source File

Tooltip Icon Props

React Properties Documentation


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.


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

VariableDefault Core Theme Value