Tooltip

A short description shown on hover and keyboard focus: dark by default, for labels and reasons, or a white hint card that explains something. For content someone opens and interacts with, use a Popup.

Installation

bun add @harmo-ui/css @harmo-ui/react

npm install @harmo-ui/css @harmo-ui/react

pnpm add @harmo-ui/css @harmo-ui/react

yarn add @harmo-ui/css @harmo-ui/react

bunx harmo-ui add tooltip

npx harmo-ui add tooltip

pnpm dlx harmo-ui add tooltip

yarn dlx harmo-ui add tooltip

Usage

import { Button, Tooltip } from "@harmo-ui/react";

<Tooltip description="Download the current view as a CSV file">
  <Button variant="secondary">Export</Button>
</Tooltip>

Examples

This site is using your theme

Describing a control

Hover a button and its tooltip shows after 300ms, then its neighbors at once; Tab to it and it shows immediately. Escape hides it. aria-describedby reads the tooltip after the button's name.

<>
  <Tooltip description="Download the current view as a CSV file">
    <Button variant="secondary">Export</Button>
  </Tooltip>
  <Tooltip description="Hide resolved tickets from the inbox">
    <Button variant="secondary">Archive</Button>
  </Tooltip>
</>

<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-describedby="export-tip">
    <span class="hbutton-label">Export</span>
  </button>
  <span class="htooltip" role="tooltip" id="export-tip">Download the current view as a CSV file</span>
</span>
<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-describedby="archive-tip">
    <span class="hbutton-label">Archive</span>
  </button>
  <span class="htooltip" role="tooltip" id="archive-tip">Hide resolved tickets from the inbox</span>
</span>

Naming an icon button

Without a label, a button can take its name from its tooltip through aria-labelledby, so screen readers say "Close, button" once instead of a name and then the same description.

<>
  <Tooltip label="Close">
    <Button variant="tertiary">
      <CloseIcon className="hicon" />
    </Button>
  </Tooltip>
  <Tooltip label="More actions">
    <Button variant="secondary">
      <MoreIcon className="hicon" />
    </Button>
  </Tooltip>
  <Tooltip label="Add contact">
    <Button>
      <PlusIcon className="hicon" />
    </Button>
  </Tooltip>
</>

<span class="htooltip-trigger">
  <button class="hbutton" data-variant="tertiary" type="button" aria-labelledby="close-tip">
    <svg class="hicon" width="24" height="24" viewBox="0 0 25 25" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">
      <path d="M18.1183 18.5318L6.80463 7.21814" />
      <path d="M18.1183 7.21814L6.80463 18.5318" />
    </svg>
  </button>
  <span class="htooltip" role="tooltip" id="close-tip">Close</span>
</span>
<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-labelledby="more-tip">
    <svg class="hicon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">
      <circle cx="6" cy="12" r="1" />
      <circle cx="12" cy="12" r="1" />
      <circle cx="18" cy="12" r="1" />
    </svg>
  </button>
  <span class="htooltip" role="tooltip" id="more-tip">More actions</span>
</span>
<span class="htooltip-trigger">
  <button class="hbutton" type="button" aria-labelledby="add-tip">
    <svg class="hicon" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">
      <path d="M12 5V19M5 12H19" />
    </svg>
  </button>
  <span class="htooltip" role="tooltip" id="add-tip">Add contact</span>
</span>

Explaining an unavailable action

aria-disabled="true" looks disabled but stays focusable and hoverable, so the tooltip can say why. A disabled button could never show it.

<Tooltip description="You don't have permission to analyze campaigns.">
  <Button aria-disabled="true">Analyze</Button>
</Tooltip>

<span class="htooltip-trigger">
  <button class="hbutton" type="button" aria-disabled="true" aria-describedby="analyze-tip">
    <span class="hbutton-label">Analyze</span>
  </button>
  <span class="htooltip" role="tooltip" id="analyze-tip">You don't have permission to analyze campaigns.</span>
</span>

Sides

Below by default; data-side prefers another side, and the tooltip flips when there isn't room. Sides are physical: left stays left in right-to-left text.

<>
  <Tooltip description="Above the button" side="top">
    <Button variant="secondary">Top</Button>
  </Tooltip>
  <Tooltip description="Below the button">
    <Button variant="secondary">Bottom</Button>
  </Tooltip>
  <Tooltip description="To the left" side="left">
    <Button variant="secondary">Left</Button>
  </Tooltip>
  <Tooltip description="To the right" side="right">
    <Button variant="secondary">Right</Button>
  </Tooltip>
</>

<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-describedby="side-top-tip">
    <span class="hbutton-label">Top</span>
  </button>
  <span class="htooltip" role="tooltip" id="side-top-tip" data-side="top">Above the button</span>
</span>
<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-describedby="side-bottom-tip">
    <span class="hbutton-label">Bottom</span>
  </button>
  <span class="htooltip" role="tooltip" id="side-bottom-tip">Below the button</span>
</span>
<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-describedby="side-left-tip">
    <span class="hbutton-label">Left</span>
  </button>
  <span class="htooltip" role="tooltip" id="side-left-tip" data-side="left">To the left</span>
</span>
<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-describedby="side-right-tip">
    <span class="hbutton-label">Right</span>
  </button>
  <span class="htooltip" role="tooltip" id="side-right-tip" data-side="right">To the right</span>
</span>

Hint

data-variant="hint" explains something, such as a KPI: a card with smaller, start-aligned text, up to 280px wide.

<Tooltip
  variant="hint"
  description="Customer satisfaction: the share of rated conversations scored 4 or 5 out of 5 in the selected period."
>
  <Button variant="tertiary">What is CSAT?</Button>
</Tooltip>

<span class="htooltip-trigger">
  <button class="hbutton" data-variant="tertiary" type="button" aria-describedby="csat-tip">
    <span class="hbutton-label">What is CSAT?</span>
  </button>
  <span class="htooltip" role="tooltip" id="csat-tip" data-variant="hint">
    Customer satisfaction: the share of rated conversations scored 4 or 5 out of 5 in the selected period.
  </span>
</span>

Inside a clipping container

The dashed container here hides whatever overflows it. The tooltip is positioned against the window, so it still shows in full.

<Tooltip description="Fixed positioning escapes the clipping container.">
  <Button variant="secondary">Hover me</Button>
</Tooltip>

<span class="htooltip-trigger">
  <button class="hbutton" data-variant="secondary" type="button" aria-describedby="clip-tip">
    <span class="hbutton-label">Hover me</span>
  </button>
  <span class="htooltip" role="tooltip" id="clip-tip">Fixed positioning escapes the clipping container.</span>
</span>

API reference

React

<Tooltip> wraps one control, its only child, and renders the tooltip after it. Pass label to name the control, as for an icon-only button, or description to describe it; the tooltip is connected through aria-labelledby or aria-describedby to match. It hides on Escape, and neighbors show at once. Other props are the trigger <span>'s attributes.

Prop	Effect
`label`	The control's name
`description`	The control's description
`side`	`top`, `left`, or `right`; below when left out
`variant`	`hint`, a white card that explains something

HTML

A <span class="htooltip-trigger"> around the control and a <span class="htooltip"> with role="tooltip" and an id, as a direct child after the control. The control takes aria-describedby, or aria-labelledby when it names an icon-only control. Load tooltip.css.

Hook	Effect
(default)	Below the trigger
`data-side="top"`, `"left"`, or `"right"`	Preferred side; it flips when there isn't room. Sides are physical, as in Radix and Floating UI: `left` stays left in right-to-left text
`data-variant="hint"`	Explains something, such as a KPI: a white card with 13px `--harmo-color-text-secondary` text, a border, and a soft shadow, up to 280px wide, start-aligned

A script is required for Escape to hide it (WCAG 1.4.13), and is optional for showing neighbors at once. See Tooltip's full contract.

Accessibility

A tooltip that describes a control is referenced with aria-describedby, so screen readers read it after the control's name.
A tooltip that names an icon-only control is referenced with aria-labelledby instead, so screen readers say "Close, button" once rather than the name and then the same description; see Button.
To explain an unavailable button, use aria-disabled="true" rather than disabled: a disabled button can't take keyboard focus, so keyboard users would never see its tooltip.