Overlays

Tooltip

Hover-and-focus triggered descriptive hint anchored to a focusable child element, wired through aria-describedby.

import { Tooltip } from '@lostgradient/cinder/tooltip';
overlayhint
01

Overview

Hover-and-focus triggered hint for terse controls, anchored to a focusable child element.

Usage

svelte 
<script lang="ts">
  import Tooltip from '@lostgradient/cinder/tooltip';
</script>

<Tooltip text="Refresh data" describe={false}>
  <button type="button" aria-label="Refresh data">R</button>
</Tooltip>
Live preview
02

When to use

Use when
  • Showing a short non-interactive label or description for an icon-only button or terse control.
  • Supplementing a control with a hint that should appear on hover or keyboard focus and dismiss on Escape.
Avoid when
  • Hosting interactive content or focusable controls — use popover instead, since tooltip content is not reachable.
  • Communicating the only accessible name for a control — use aria-label or visible text rather than tooltip text.
03

Examples

Basic tooltip

Hover or focus the trigger to show the tooltip text.

Tooltip placements

Top, right, bottom, and left placement options.

Transformed ancestor anchoring

Hover the trigger after scrolling the transformed preview shell to verify tooltip fixed-position anchoring.

04

Props

Props for tooltip
NameTypeDefaultDescription
text required text Text content rendered inside the tooltip.
placement 'top' | 'right' | 'bottom' | 'left' 'top' Preferred side of the trigger on which the tooltip appears. Default top.
describe boolean true Whether to wire tooltip text to the trigger via aria-describedby.
triggerRef HTMLElement | null null Explicit anchor element, for when the tooltip cannot wrap its trigger. The default form renders a wrapper around children and resolves the anchor from it, which puts the role="tooltip" panel inside whatever structure the trigger sits in. That is wrong wherever the surrounding markup constrains its children — AvatarGroup wraps each avatar in a role="listitem", so an in-tree panel lands inside a list item. With triggerRef, the Tooltip renders ONLY the panel and anchors it to the supplied element, so the consumer places the panel wherever it belongs. children is then unnecessary — the trigger is already in the consumer's own markup. Mirrors PopoverProps.triggerRef.
children snippet The trigger element the tooltip wraps and anchors to. Required unless triggerRef supplies the anchor instead.