{"slug":"tooltip","name":"Tooltip","packageName":"@liquidify/react","category":"presentational","maturity":"stable","summary":"A short glass label that floats next to a trigger while the pointer hovers it or the trigger holds keyboard focus, describing that trigger — the web analogue of SwiftUI's .help(:) (macOS / iPadOS-with-pointer) and UIKit's UIToolTipInteraction (iPadOS 16+).","importPath":"@liquidify/react/tooltip","sourcePath":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx","specPath":"packages/@liquidify/react/src/components/tooltip/spec.md","docsPath":"../liquidify-page/content/component-source/tooltip.md","documentationStatus":"stable","storyIds":["presentational-tooltip--default"],"additionalExports":["DEFAULT_TOOLTIP_DELAY_MS","TooltipAlign","TooltipPlacement"],"anatomy":[{"name":"wraps the consumer's trigger element (e.g. a","description":"wraps the consumer's trigger element (e.g. a"},{"name":"is the portalled glass label","description":"is the portalled glass label"}],"props":[{"name":"align","type":"TooltipAlign | undefined","required":false,"description":"Cross-axis alignment of the panel against the trigger.","defaultValue":"`\"center\"`","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"aria-label","type":"string | undefined","required":false,"description":"Accessible name of the panel itself, if needed beyond `aria-describedby`.","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"aria-labelledby","type":"string | undefined","required":false,"description":"Id of the element labelling the panel.","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"className","type":"string | undefined","required":false,"description":"Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"defaultOpen","type":"boolean | undefined","required":false,"description":"Uncontrolled seed for the open state.","defaultValue":"`false`","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"delay","type":"number | undefined","required":false,"description":"Hover-open delay in milliseconds; keyboard focus opens immediately.","defaultValue":"{@link DEFAULT_TOOLTIP_DELAY_MS }","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"label","type":"ReactNode","required":true,"description":"The tooltip's short text body — mirrors `.help`'s single text argument.","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"material","type":"\"frosted\" | \"regular\" | \"clear\" | undefined","required":false,"description":"Material of the glass surface — `frosted · regular · clear` (§06). Forwarded to the engine, which resolves the chain `prop ?? <Material default> ?? \"regular\"`, so a bare surface inherits the enclosing provider default.","defaultValue":"enclosing `<Material default>`, else `\"regular\"`","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"onOpenChange","type":"((open: boolean) => void) | undefined","required":false,"description":"Fires with the next boolean on every show/hide path.","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"open","type":"boolean | undefined","required":false,"description":"Controlled open state.","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"perf","type":"\"low\" | \"high\" | undefined","required":false,"description":"Perf budget of the glass surface (ADR-0006/0007). Forwarded to the engine as `data-glass-perf`; `\"high\"` opts this surface into the edge-lensing filter. When omitted, derives from the enclosing `<Backdrop type>` (§04).","defaultValue":"derived from `<Backdrop type>`, else `\"low\"`","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"placement","type":"TooltipPlacement | undefined","required":false,"description":"Which trigger edge the panel sits on (forwarded to `Popup`).","defaultValue":"`\"top\"`","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"},{"name":"ref","type":"Ref<HTMLDivElement> | undefined","required":false,"description":"Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"trigger","type":"ReactNode","required":true,"description":"The anchored trigger element, merged via `Popup.Trigger asChild`.","declaredIn":"packages/@liquidify/react/src/components/tooltip/tooltip.tsx"}],"swiftUIMap":[{"swiftUI":"`.help(_ textKey: LocalizedStringKey)` / `.help(_ text: Text)` / `.help<S>(_ string: S)` / `UIToolTipConfiguration.title`","react":"`label: ReactNode`","notes":"The tooltip's text body — mirrors `.help`'s single text argument. **Text / inline only, no focusable descendants** (APG); enforcement is a runtime dev warning (Open questions §8). `label` vs `content` naming is Open questions §8.","relationship":"direct"},{"swiftUI":"(the modified view)","react":"`trigger: ReactNode`","notes":"The anchored element, merged via `Popup.Trigger asChild` (ADR-0016); receives **`aria-describedby`** (only while shown), **not** the disclosure triad.","relationship":"direct"},{"swiftUI":"(system-owned placement)","react":"`placement?: \"top\" | \"bottom\" | \"left\" | \"right\"`","notes":"Forwarded to `Popup`. `placement` names the *trigger* side the panel sits on (Popup-native), with collision auto-flip. Apple exposes no placement API → default `\"top\"` is an inference (Open questions §4).","relationship":"direct"},{"swiftUI":"`attachmentAnchor` (no `.help` analogue)","react":"`align?: \"start\" | \"center\" | \"end\"` (`\"center\"` default)","notes":"Popup's cross-axis alignment.","relationship":"direct"},{"swiftUI":"(system-owned show delay)","react":"`delay?: number` (ms)","notes":"Hover-open delay; keyboard-focus opens immediately (APG). Apple exposes no public value → a token-backed default (`--lq-tooltip-delay`, value TBD) is proposed (Open questions §7). *Inference.*","relationship":"direct"},{"swiftUI":"`UIToolTipInteraction` open/close (system)","react":"`open?` / `defaultOpen?` / `onOpenChange?`","notes":"Presentation triad (ADR-0015 / ADR-0017) — **optional**; the primary driver is hover/focus, not a controlled click. `open` is controlled iff `open !== undefined` (audit §8). Whether to expose the triad at all is Open questions §5.","relationship":"direct"},{"swiftUI":"(presentation chrome)","react":"`material?` / `perf?`","notes":"`PresentationalProps` (ADR-0023) — the label's glass surface (default `frosted`, an inference — no sim; Open questions §6). Materials: `frosted` · `regular` · `clear`. The base is tint-free (no `tint` axis).","relationship":"direct"},{"swiftUI":"`.help` supplies the a11y help/hint","react":"`aria-label` / `aria-labelledby`","notes":"The label text is the accessible **description** of the trigger (`aria-describedby`), not a name; a supplied `aria-label` names the panel itself only if needed.","relationship":"direct"},{"swiftUI":"(no SwiftUI analogue)","react":"`ref?: Ref<HTMLDivElement>`","notes":"`TooltipProps extends PresentationalProps<HTMLDivElement>` — forwarded to the semantic root, the portalled `role=\"tooltip\"` glass panel; attached while shown, `null` while hidden.","relationship":"web-only"}],"tokens":["--lq-color-label-primary-","--lq-duration-","--lq-easing-","--lq-glass-","--lq-hit-target-touch","--lq-popup-","--lq-popup-x","--lq-popup-y","--lq-radius-","--lq-tooltip-delay","--lq-tooltip-max-width","--lq-tooltip-pad"],"keyboard":[{"key":"Keyboard","action":"Keyboard (via Popup, APG Tooltip): the label shows on trigger focus-in and hides on trigger blur; Escape dismisses it while the trigger keeps focus (WCAG dismissable). The panel itself is never focusable and never in the tab order — Tab moves between triggers, never into the label."}],"variants":[],"variantPages":[]}