Tooltips are meant to be used for supplemental content and should never be used for critical information the user needs to complete a task. Tooltips may not contain interactive elements (such as buttons or links).

Usage

Tooltips should:

Provide useful, additional information or clarification.
Succinctly describe or expand on the element they point to.
Be provided for icon-only buttons or a button with an associated keyboard shortcut.
Be used sparingly. Prefer clarifying the design and the language in the experience.

Basic

Tooltips are displayed to the user on hover or focus of the target element.

IMPORTANT: Tooltips cannot be applied to icons. Notice that we're wrapping the icon and providing an aria-label, this is required for accessibility.

Edit in Playroom

<Inline>
  <Tooltip content="This is a tooltip!">
    <Box aria-label="Help">
      <HelpCircleIcon color="dim" />
    </Box>
  </Tooltip>
</Inline>

Placement

The placement of the tooltip relative to the target.

Edit in Playroom

<Inline gap="small">
  <Tooltip content='The placement is "top"' placement="top">
    <ActionButton label="Top" />
  </Tooltip>
  <Tooltip content='The placement is "right"' placement="right">
    <ActionButton label="Right" />
  </Tooltip>
  <Tooltip content='The placement is "bottom"' placement="bottom">
    <ActionButton label="Bottom" />
  </Tooltip>
  <Tooltip content='The placement is "left"' placement="left">
    <ActionButton label="Left" />
  </Tooltip>
</Inline>

Formatting

To ensure readability, tooltips have a maximum width of 260px, which means that text will wrap onto multiple lines if you provide enough content.

You can also use multiple text elements and layout components to create more custom layouts.

Edit in Playroom

<Tooltip
  content={
    <Stack gap="small">
      <Text size="small" weight="bold">
        Some title
      </Text>
      <Text size="small">
        Some content that will wrap on to multiple lines. The quick brown fox
        jumps over the lazy dog.
      </Text>
    </Stack>
  }
>
  <ActionButton label="Hover over me" />
</Tooltip>

Conditional rendering

A tooltip must always have content.

IMPORTANT: Do not provide an empty string or other falsy data to the tooltip "content" prop. Instead, conditionally render the tooltip itself. This is required for accessibility.

Remember that you can compose Balance components to create your own:

import { TooltipProps, Tooltip } from '@balance-web/tooltip';
type ConditionalTooltipProps = { when: boolean } & TooltipProps;
export const ConditionalTooltip = ({
  children,
  when,
  ...tooltipProps
}: ConditionalTooltipProps) => {
  if (when) {
    return <Tooltip {...tooltipProps}>{children}</Tooltip>;
  }
  return children;
};

Then use them in your app:

<ConditionalTooltip when={someCondition} content="Tooltip for disabled button">
  <Button disabled={someCondition} label="Some label" />
</ConditionalTooltip>