Tooltip

Tooltips display informative text when users hover, focus, or tap an interactive element.

Make sure to read the Accessibility section for best practices before using tooltips.

Usage

Wrap Tooltip around the element you want to use as the “trigger”, and pass the tooltip text into the content prop.

import * as React from 'react';
import { Tooltip, Button } from '@itwin/itwinui-react';

export default () => {
  return (
    <Tooltip content='I am a tooltip'>
      <Button>Please, hover me!</Button>
    </Tooltip>
  );
};

For everything to work correctly, the trigger element must:

• be an interactive element, for example, a <button>
• forward its ref
• delegate (spread) any arbitrary props to the underlying DOM node

Positioning

Tooltip handles positioning using an external library called Floating UI. To control which side the tooltip should be placed relative to its trigger, use the placement prop (which defaults to "top"). If enough space is not available, then it will automatically flip to the opposite side.

import * as React from 'react';
import { Tooltip, Button } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <Tooltip placement='left' content='left tooltip'>
        <Button>Left</Button>
      </Tooltip>
      <Tooltip placement='top' content='top tooltip'>
        <Button>Top</Button>
      </Tooltip>
      <Tooltip placement='bottom' content='bottom tooltip'>
        <Button>Bottom</Button>
      </Tooltip>
      <Tooltip placement='right' content='right tooltip'>
        <Button>Right</Button>
      </Tooltip>
    </div>
  );
};

There are some advanced props available for more granular control over positioning, such as autoUpdateOptions and middleware. These are rarely needed in practice.

Portals

It is important to know that before calculating the position, the tooltip gets portaled into the nearest ThemeProvider to avoid stacking context issues. This behavior can be controlled using the Tooltip’s portal prop or the ThemeProvider’s portalContainer prop.

Accessibility

Tooltip has a few built-in accessibility features to help satisfy WCAG Success Criterion 1.4.13.

• The tooltip will be shown when the trigger element is focused (e.g. using the Tab key).
• The tooltip can be dismissed using the Escape key.
• The content can be hovered over using a mouse pointer, instead of always disappearing when the pointer leaves the trigger element.
• For screen-reader support, the tooltip will be associated with the trigger element using aria-describedby by default. This behavior is controllable using the ariaStrategy prop.

Best practices

• Tooltips should only be used to display supplemental information. Do not use tooltips to display critical information, or as a means to navigate an interface. Functionality of the product should not be dependent on the user reading tooltips.

• Tooltip content should consist of short plain text, up to 256 characters. Do not use content other than text, such as links, pictures, tables, etc. If you need to display more interactive content, consider using a Popover instead.

• Tooltips should only be triggered by interactive elements, such as buttons, which can be focused using keyboard. Do not use tooltips for revealing truncated text and do not use plain icons as the trigger, as this pattern will not be accessible to keyboard users or screen-reader users.

• Touchscreen devices do not have a hover state. Be cautious when using tooltips, since there is no determined way of replacing tooltips on mobile devices or tablets.

IconButtons

If you are using an IconButton as the trigger, you can pass the label prop to it, instead of wrapping it in a Tooltip component. This will automatically add the tooltip functionality to the button and handle some other accessibility considerations as well.

<IconButton label='Edit'>
  <SvgEdit />
</IconButton>

Props