Tooltip

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

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.

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.

<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.

<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.

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

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

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.

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.

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.