Tooltip · SWSHD Documentation

Overview

Tooltip names a control whose label is not visible — a collapsed sidebar item, an icon-only button. It is a supplement, not a replacement for an accessible name.

Web only; native renders the child.

A rounded bubble at least 28 px tall, painted from TOOLTIP_TOKENS: fill.raised.default with text.strong ink, a border.default ring, and an optional kbd chip — fill.subtle.pressed with text.primary.

Tooltips, chart tooltips, and collapsed sidebar quick-action menus use the same Tooltip/Surface frame and label parts for their fill, border, corners, padding, and typography.

Labels use body-md in Gerstner, sentence case. Shortcut keycaps use label-md in uppercase mono.

Settings

Collapse sidebar

[

Try it

Hover or focus a button.

top

bottom

left

right

Text wrapping

Long labels wrap at 280 px by default. Set maxWidth to customize the width in pixels; the bubble stays within the viewport and grows vertically. Short labels keep their natural width.

Timing

Opens immediately on hover by default (TOOLTIP_TIMING.openDelay: 0 ms), including the first entry. An explicit openDelay applies on every pointer entry; keyboard focus opens instantly. Tooltips and collapsed sidebar groups share one active owner, so moving between anchors dismisses the previous surface immediately. The enter is motion.duration.fast (120 ms), disabled under prefers-reduced-motion, the app's reduceMotion, and automation. It hides on leave, blur, press, scroll, or any key.

Usage

import Tooltip from "swshd/Tooltip";
import type { TooltipProps, TooltipPlacement } from "swshd/Tooltip";
import ButtonRoot from "swshd/Button/Root";
import ButtonIcon from "swshd/Button/Icon";

<Tooltip label="Settings" placement="right" disabled={!collapsed}>
  <ButtonRoot iconOnly accessibilityLabel="Settings" onPress={open}>
    <ButtonIcon Icon={IconGear} />
  </ButtonRoot>
</Tooltip>

Accessibility

The bubble is role="tooltip". It is not linked to the anchor, so the anchor must carry its own accessible name (accessibilityLabel). Keyboard focus-visible opens it.

API

Prop	Type	Default	Description
`label`	`string`	—	The label, sentence case.
`kbd`	`string`	—	Optional keycap after the label.
`maxWidth`	`number`	`280`	Maximum bubble width in pixels, capped to the viewport. Long labels wrap.
`placement`	`"right" \| "left" \| "top" \| "bottom"`	`"right"`	Which side of the anchor.
`disabled`	`boolean`	`false`	Never open.
`children`	`ReactElement`	—	The anchor element.
`testID`	`string`	—	data-testid on the bubble.