Tooltip usage guidelines

A tooltip is a floating, non-interactive label that provides additional context about a user interface element or feature.

When to use

• For displaying non-essential supporting information.
• To assist in explaining interactive elements that display an icon with no visible label.
• To provide clarity about an interaction.

When not to use

• For obvious information or repetitive content.
• Critical task-related information should not be hidden in a tooltip, and should be part of the standard page layout instead.
• Use popovers if the floating content contains interactive elements.

Tooltip vs. popover
Tooltips and popovers are similar concepts that often get confused:

• Tooltips are shown when the trigger element is hovered or focused. They cannot contain interactive elements, they are inaccessible to screen readers, and they cannot be displayed on touchscreens.
• Popovers are shown when the trigger element is pressed. They can contain interactive elements, they are accessible to screen readers, and they can be displayed on touchscreens.

Usage

Preview

Hover or focus the button to make the tooltip appear.

Code

import { IconButton, Stack, Text, Tooltip } from '@cimpress-ui/react';
import { IconAdd } from '@cimpress-ui/react/icons';

export default function Demo() {
  return (
    <Stack gap={16}>
      <Tooltip label="Add product">
        <IconButton icon={<IconAdd />} aria-label="Add product" />
      </Tooltip>

      <Text as="p" variant="medium">
        Hover or focus the button to make the tooltip appear.
      </Text>
    </Stack>
  );
}

Properties

Placement

Preview

Hover or focus the buttons to make the tooltips appear.

Code

import { IconButton, Stack, Text, Tooltip } from '@cimpress-ui/react';
import { IconArrowDown, IconArrowLeft, IconArrowRight, IconArrowUp } from '@cimpress-ui/react/icons';

export default function Demo() {
  return (
    <Stack gap={16}>
      <Stack gap={16} direction="horizontal" wrap>
        <Tooltip label="This tooltip is above the button." placement="top">
          <IconButton icon={<IconArrowUp />} aria-label="Above" />
        </Tooltip>
        <Tooltip label="This tooltip is below the button." placement="bottom">
          <IconButton icon={<IconArrowDown />} aria-label="Below" />
        </Tooltip>
        <Tooltip label="This tooltip is to the left of the button." placement="left">
          <IconButton icon={<IconArrowLeft />} aria-label="Left" />
        </Tooltip>
        <Tooltip label="This tooltip is to the right of the button." placement="right">
          <IconButton icon={<IconArrowRight />} aria-label="Right" />
        </Tooltip>
      </Stack>

      <Text as="p" variant="medium">
        Hover or focus the buttons to make the tooltips appear.
      </Text>
    </Stack>
  );
}

The placement of the tooltip with respect to the trigger element.

Best practices

• Before using a tooltip, explore if the information can be made readily available through clearer UI design.
• Ensure that your UI is usable without relying on tooltip content. Assume that tooltip content will never be read.
• Tooltips should only contain short, informative text. Do not include links or interactive elements, as this creates accessibility and usability issues.
• Avoid placing critical information in tooltips. Due to their limited discoverability and lack of hover interaction on some devices, they are unreliable for conveying essential details.
• Never use tooltips on disabled elements. This creates an inaccessible and unsupported user experience.

Formatting and layout

Placement

Tooltips will appear above the trigger element by default, but placement can vary based on tooltip properties and available space within the viewport. The trigger should be an interactive element, for example an icon button.

Size

Tooltips are sized dynamically based on the content inside. They have a maximum width of 240px, and a maximum height of 5 lines of text.

Content writing

• Avoid repeating content inside a tooltip if there’s already a visible label.
• Tooltips should provide relevant, specific context.
• Avoid placing critical task instructions within tooltips.
• For icon-only components, use tooltips to clearly define their function with short descriptions. For example, say “Add new product” instead of “Add new business card in Product Catalog Dashboard for Vistaprint”.

Behaviors

Delay

Tooltips appear after a brief pause when hovering over the trigger element, or immediately when using keyboard focus. They remain visible during short pointer movements away from the target.

Persistence

Tooltips persist as long as the user hovers on the trigger element or on the tooltip itself, or as long as the trigger element has keyboard focus. Tooltips can be dismissed by pressing the Escape key.