Tooltip

Usage

Help icons

Need a "?" icon with an explanatory tooltip? Use HelpIndicator — it renders the icon, the button, the label and the tooltip correctly so you don't have to compose them:

Basic

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

IMPORTANT: The trigger must be an interactive element (a button, link, or form control). Screen readers announce the tooltip content as the trigger's accessible description, and they only do this reliably for real controls — VoiceOver reads a labelled Box or span as a bare "group" and skips the tooltip content entirely. Non-interactive triggers are flagged by the @reckon-web/tooltip-interactive-trigger lint rule and warned about at runtime in development.

Placement

The placement of the tooltip relative to the target.

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.

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>

Testing

The tooltip component supports providing testids via the data prop.

<Tooltip content="Tooltip content" data={{ testid: 'my-tooltip' }}>
  <ActionButton label="Hover over me" />
</Tooltip>

Note While the tooltip itself has a testid, the trigger will not automatically gain one. You can provide a testid to the trigger element if you need to target it specifically in your tests.