Storybook
SketchExamples
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
Inline
Interactive content
With Close
Code
React
| Name | Type | Default | Description |
|---|---|---|---|
activeClassName | string | Classes applied to the tooltip trigger when the tooltip is active | |
ariaLabel | string | Helpful description of the tooltip for screenreaders | |
childrenrequired | ReactNode | Tooltip trigger content | |
className | string | Classes applied to the tooltip trigger | |
closeButtonLabel | string | Configurable text for the aria-label of the tooltip's close button | |
component | 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. |
contentHeading | ReactNode | Heading for the tooltip content. This will show above 'title' content and inline with 'closeButton' if closeButton is set | |
dialog | boolean | 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 | string | id applied to tooltip body container element. If not provided, a unique id will be automatically generated and used. | |
interactiveBorder | number | 15 | Sets the size of the invisible border around interactive tooltips that prevents it from immediately hiding when the cursor leaves the tooltip. |
inversed | boolean | ||
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 | Placement | top | Placement of the tooltip body relative to the trigger. See the popperjs docs for more info. |
maxWidth | string | 300px | maxWidth styling applied to the tooltip body |
showCloseButton | boolean | Determines if close button is shown in tooltip. It is recommended that the close button is only used if dialog=true | |
titlerequired | ReactNode | Content inside the tooltip body or popover. If contains interactive elements use the dialog prop. | |
transitionDuration | number | 250 | Duration of the react-transition-group CSSTransition. See the timeout option for more info. |
zIndex | number | 9999 | 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.
| Name | Type | Default | Description |
|---|---|---|---|
inversed | boolean | If true sets inverse fill color. | |
className | string | Additional CSS classes to be added to the svg element | |
ariaHidden | boolean | Describes 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. | |
id | string | A custom id attribute for the SVG | |
title | string | The descriptive name for the SVG icon | |
viewBox | string | A 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. | |
description | string | Long-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:
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.