Skip to main content
U.S. Flag

An official website of the United States government

Tooltip

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

Warning: draftGithubStorybook logoStorybookSketch logoSketch

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
activeClassNamestring

Classes applied to the tooltip trigger when the tooltip is active

ariaLabelstring

Helpful description of the tooltip for screenreaders

childrenrequiredReact.ReactNode

Tooltip trigger content

classNamestring

Classes applied to the tooltip trigger

closeButtonLabelstring

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.

contentHeadingReact.ReactNode

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

dialogboolean

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

idstring

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

interactiveBordernumber15

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

Called when the tooltip is hidden

onOpen() => any

Called when the tooltip is shown

placementPlacement'top'

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

maxWidthstring'300px'

maxWidth styling applied to the tooltip body

showCloseButtonboolean

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

titlerequiredReact.ReactNode

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

transitionDurationnumber250

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

zIndexnumber9999

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

Styles

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

Sass variables for tooltip
VariableDefault Core Theme Value
$tooltip__background-color$color-white
$tooltip__border-color$color-gray-dark
$tooltip__color$color-base
$tooltip__box-shadow-color$color-gray-light
$tooltip-icon__color$color-primary
$tooltip-icon__color--inverse$color-white
$tooltip-trigger__color$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.