Tooltip

The default title="" attribute is fast to write and slow to render; the browser shows it after about 1500 ms, in its own un-themed font, with no shortcut hint, and no flipping if it would clip the viewport. <Tooltip> replaces it everywhere the library shows one and is available for consumer code to use the same way.

Hover a dock tile or a workspace pip to see the themed tooltip Open in new tab ↗

Import

import { Tooltip } from "@react-ui-os/desktop";

Wrap a single element

<Tooltip text="Save" shortcut="⌘S">
  <button onClick={save}>
    <SaveIcon />
  </button>
</Tooltip>

Tooltip clones its child to inject pointer / focus handlers. The child must be a single React element that accepts those handlers: a <button>, a <div>, a <span>, or anything that forwards them.

Props

Prop	Type	Default	Description
`text`	`string`	none	Body line. Keep glanceable.
`shortcut`	`string`	none	Optional right-aligned hint (`"⌘K"`, `"F2"`, `"↵"`).
`placement`	`"top" \| "bottom" \| "left" \| "right"`	`"top"`	Preferred edge. Flips automatically if it would clip.
`disabled`	`boolean`	`false`	Suppress without unwrapping the child.

Behavior

Show delay: ~480 ms first time, ~60 ms while warm. Once any tooltip has hidden in the last ~800 ms, the next one comes up almost instantly. Moving the cursor between dock tiles doesn’t re-pay the delay.
Hide: pointer leave or blur. No persistent hover-on-tooltip behavior to avoid stuck states.
Flipping: the surface measures itself; if the preferred placement would overflow the viewport, it flips to the opposite edge. Final clamp keeps it on-screen no matter what.
Focus access: <Tooltip> listens for onFocus / onBlur too, so keyboard-only users see the same hint when they tab to an element.
Pointer-events: none: the tooltip never blocks the cursor. You can keep clicking through it onto the underlying element.

Where the library uses it

Dock tiles (app name)
Workspace pips (Workspace N + ⌃⌥<number>)
Menu-bar clock / Notification Center button
Window traffic lights (via the same component in a future round)
FileExplorer toolbar buttons (via a future migration)

Accessibility

Surface is role="tooltip". Screen readers read the original element’s aria-label (or title, or text); the tooltip body is supplementary, not authoritative. Keep aria-label semantically meaningful.
Honoring focus events means keyboard navigation lights up the tooltip the same way hover does.
The text you pass is rendered as visible content; do not use it as the only label for an icon-only button. Add an aria-label to the button itself.