Skip to contentSkip to navigationSkip to topbar
Figma
Star

Tooltip

Peer review pending

A Tooltip is a page overlay that displays non-interactive clarifying text related to an element that’s in a focused or hovered state.

Version 11.1.1
Github
Component preview theme
<Tooltip text="Black Lives Matter. We stand with the Black community.">
<Button variant="primary">✊ Action</Button>
</Tooltip>

Guidelines

Guidelines page anchor

About Tooltip

About Tooltip page anchor

The Tooltip component is a popup that displays text related to an element when the element is focused via the keyboard or on mouse hover. They should never contain information essential to task completion, or be used for an error. Tooltip follows the WAI-ARIA Tooltip Pattern(link takes you to an external page).

Tooltip compared to Popover

Tooltip compared to Popover page anchor

A tooltip must be placed on only a natively focusable HTML element, like an enabled Button or an Anchor. Do not place tooltips on non-focusable elements, like an icon, or disabled components, like a button. Keyboard users cannot focus on disabled components.

If your tooltip wraps a natively focusable HTML element that includes only an icon, make sure you set the prop decorative={false}, and give the icon a title. The title of the icon should be the accessible name for the button action, like "Delete phone number". The tooltip provides the additional context, like "You can delete phone numbers every 7 days". This ensures the icon and tooltip are accessible to screen readers. Refer to the focusable element example for implementation.

When the user focuses an element with a tooltip, their focus stays on the element. Since focus never goes inside the tooltip, do not use additional components, like an Anchor, within the Tooltip.

Component preview theme
<Tooltip text="Black Lives Matter. We stand with the Black community.">
<Button variant="primary">✊ Action</Button>
</Tooltip>

The placement of the tooltip is configurable via the placement prop. The available placement options are available in the props description here. No matter the placement, the tooltip will always adjust to remain in the screen so you don't have to worry about it going off the page, or being covered by another element.

Component preview theme
<Tooltip text="Welcome to Paste!" placement="right">
<Button variant="primary">Open Tooltip</Button>
</Tooltip>

A tooltip must be placed on a focusable element, such as an anchor or button.

Do not place tooltips on non-focusable elements, like an icon. Wrap them in a focusable element and place the tooltip on that.

Component preview theme
<Box display="flex" alignItems="center">
<Text as="span">Social Security Number</Text>
<Tooltip text="Your nine-digit Social Security number is your first and continuous connection with Social Security.">
<Anchor href="https://paste.twilio.design">
<InformationIcon decorative={false} title="Open Tooltip" display="block" />
</Anchor>
</Tooltip>
</Box>

Tooltips require their children to forwardRefs

Tooltips require their children to forwardRefs page anchor

If you want to add a Tooltip around a React component, you must make sure that component forwards refs(link takes you to an external page). All Paste components do this by default, so this is only a concern when placing Tooltips around other types of components.

Component preview theme
const FancyButton = React.forwardRef((props, ref) => (
<button ref={ref} {...props} style={{backgroundColor: 'white', border: '1px solid #000', color: '#000', borderRadius: '5px', padding: '5px'}}>
Fancy button: {props.children}
</button>
));
const NonPasteChildComponent = () => {
return (
<Tooltip text="Forwarding refs correctly!">
<FancyButton>Fancy!</FancyButton>
</Tooltip>
);
};
render(
<NonPasteChildComponent />
)

The tooltip comes with the option of "hooking" into the internal state by using the state hook originally provided by Reakit(link takes you to an external page).

Rather than the state be internal to the component, you can use the useTooltipState hook and pass the returned state to Tooltip as the state prop.

This allows you to use certain returned props from the state hook, including functions like hide and show.

An example usecase of this might be programmatically providing the user a tooltip when a certain user action is taken. In the example below we are showing a tooltip when another button is pressed. When pressed the button uses the show function from the hook. Another button using the hide function from the hook is also provided to hide the tooltip when pressed.

It should be noted that when doing so, the state prop takes precident over the other properties that affect the state or initial state of the Tooltip. They will be ignored in favour of them being provided as arguments to the useTooltipState hook.

For full details on how to use the state hook, and what props to provide it, follow the Tooltip Primitive documentation. It's the same hook, just renamed.

Component preview theme
const StateHookExample = () => {
const tooltip = useTooltipState();
return (
<Stack orientation="horizontal" spacing="space60">
<Tooltip
state={tooltip}
text="This should be visible by pressing another button"
>
<Button variant="primary">Open tooltip</Button>
</Tooltip>
<Button variant="secondary" onClick={() => tooltip.show()}>
Open tooltip on click
</Button>
<Button variant="secondary" onClick={() => tooltip.hide()}>
Close tooltip on click
</Button>
</Stack>
);
};
render(
<StateHookExample />
)

Tooltips can only contain text content, and should contain only information that is useful additional context or guidance for the user. If you need to include an Anchor or icons, use a Popover instead.

Never put information essential to task completion in a Tooltip. Furthermore, Tooltips are easily overlooked and disappear when not focused on, so consider whether the information may be better served by another component. Use Help Text, which is persistent and more obvious, for essential information.

Do not use a Tooltip on a disabled Button to explain why the button is unavailable. The disabled button isn't focusable.

Use full sentences and punctuation. Include no more than three lines of text.

Do

Use Tooltips to provide additional helpful information or guidance.

Don't

Don't use Tooltips for information essential to task completion.

Do

Use Tooltips only on focusable elements.

Don't

Don't use Tooltips on non-focusable elements, like icons and disabled buttons.

Do

Include only text in Tooltip content.

Don't

Don't include links in Tooltip content.