Skip to content

Tooltip

A short text label that appears on hover or keyboard focus to name or explain a control.

betaReact AriaSource

Installation

pnpm add @syntara/react @syntara/tokens
import { Tooltip, TooltipTrigger } from '@syntara/react';

Usage

import { Button, Tooltip, TooltipTrigger } from '@syntara/react';
import { IconCopy } from '@syntara/icons';

export function CopyButton() {
  return (
    <TooltipTrigger>
      <Button variant="ghost" size="icon" aria-label="Copy reference">
        <IconCopy aria-hidden />
      </Button>
      <Tooltip>Copy reference</Tooltip>
    </TooltipTrigger>
  );
}

Examples

Icon buttons

Shows the accessible name of icon-only buttons to sighted users.

Placement

top, bottom, start and end; start and end follow the reading direction.

Accessibility

KeysAction
TabFocusing the trigger shows the tooltip immediately.
EscapeHides the tooltip without moving focus.
  • role="tooltip"; the trigger is described by it via aria-describedby while it is open.
  • Hover opening starts after the user has used a pointer on the page (React Aria's interaction modality); keyboard focus always opens it.
  • Tooltips are not reachable on touch devices: never put essential information or interactive content in them.
  • Overlays render in a portal on <body>, outside any ThemeScope. When it opens, the overlay looks up data-syntara-theme, data-syntara-scheme, data-syntara-density, dir and lang — each on the nearest ancestor that has it — starting from its trigger (or from where the component is rendered, when controlled), and copies them onto its own root — so it uses the same tenant tokens and direction as the page region it came from, and nested overlays inherit from their parent overlay.
  • Tooltips stay solid surface.inverse (too small to read as glass). They fade in fast with a 4px slide from the trigger's side; with prefers-reduced-motion they appear without moving.

Guidelines

Do

  • Pair every icon-only button with a Tooltip repeating its aria-label.
  • Keep it to a few words.

Don’t

  • Don't put links or buttons in a tooltip — use a Popover.
  • Don't use tooltips on disabled buttons to explain why; show the reason inline.

API reference

Tooltip

childrenRequired
ReactNode

Short plain text.

placement
Placement

Preferred side. Flips when there is no room.

Default 'top'

showArrow
boolean

Draws an arrow pointing at the trigger.

Default true

offset
number

Distance from the trigger in px.

Default 8 (6 without arrow)

className
string | (state) => string

Merged onto the tooltip root.

TooltipTrigger

delay
number

Hover delay in ms before the first tooltip opens. Keyboard focus opens immediately.

Default 600

closeDelay
number

Delay in ms before closing after the pointer leaves.

Default 0

isDisabled
boolean

Turns the tooltip off.

Default false

trigger
'focus'

Open only on keyboard focus, not hover.

Tokens

The semantic tokens this component reads, grouped by what they control. Swatches show this site’s theme; change a tenant’s brand and the component follows with no code change.

Colour2
surface.inversetext.inverse
Type4
font.bodyfont.size.xsfont.weight.mediumline-height.snug
Space and size4
space.16space.4space.1space.2
Shape1
radius.button
Depth2
shadow.highlightshadow.raised
Motion3
motion.duration.fastmotion.easing-outmotion.easing