Overlays
Tooltip
A dark label that appears on hover or keyboard focus. Use it to name icon buttons or add a short hint, never for content people must read.
import * as Tooltip from '@statix/ui/tooltip';Playground
<Tooltip.Provider>
<Tooltip.Root>
<Tooltip.Trigger>
{#snippet child({ props })}
<Button variant="outline" size="icon" aria-label="Call support" {...props}>
<PhoneIcon />
</Button>
{/snippet}
</Tooltip.Trigger>
<Tooltip.Content>Jonas Weber, 040 468 970 790</Tooltip.Content>
</Tooltip.Root>
</Tooltip.Provider>Examples
On icon buttons
The most common use. The tooltip repeats or extends the aria-label, so mouse users see what screen readers hear.
<script lang="ts">
import * as Tooltip from '@statix/ui/tooltip';
import { Button } from '@statix/ui/button';
import PhoneIcon from '@lucide/svelte/icons/phone';
import DownloadIcon from '@lucide/svelte/icons/download';
import CopyIcon from '@lucide/svelte/icons/copy';
const actions = [
{ label: 'Call support', hint: 'Jonas Weber, 040 468 970 790', icon: PhoneIcon },
{ label: 'Download invoice', hint: 'Download invoice as PDF', icon: DownloadIcon },
{ label: 'Copy domain', hint: 'Copy yoga-berger.de', icon: CopyIcon }
];
</script>
<Tooltip.Provider>
{#each actions as action (action.label)}
<Tooltip.Root>
<Tooltip.Trigger>
{#snippet child({ props })}
<Button variant="outline" size="icon" aria-label={action.label} {...props}>
<action.icon />
</Button>
{/snippet}
</Tooltip.Trigger>
<Tooltip.Content>{action.hint}</Tooltip.Content>
</Tooltip.Root>
{/each}
</Tooltip.Provider>Sides
top is the default. The tooltip flips when there is no room.
<script lang="ts">
import * as Tooltip from '@statix/ui/tooltip';
import { Button } from '@statix/ui/button';
const sides = ['top', 'right', 'bottom', 'left'] as const;
</script>
<Tooltip.Provider>
{#each sides as side (side)}
<Tooltip.Root>
<Tooltip.Trigger>
{#snippet child({ props })}
<Button variant="outline" class="capitalize" {...props}>{side}</Button>
{/snippet}
</Tooltip.Trigger>
<Tooltip.Content {side}>Last backup today at 03:10</Tooltip.Content>
</Tooltip.Root>
{/each}
</Tooltip.Provider>With a shortcut
A Kbd inside the tooltip gets a light fill on the dark background.
<script lang="ts">
import * as Tooltip from '@statix/ui/tooltip';
import { Button } from '@statix/ui/button';
import { Kbd } from '@statix/ui/kbd';
import SearchIcon from '@lucide/svelte/icons/search';
</script>
<Tooltip.Provider>
<Tooltip.Root>
<Tooltip.Trigger>
{#snippet child({ props })}
<Button variant="secondary" size="icon" aria-label="Search" {...props}>
<SearchIcon />
</Button>
{/snippet}
</Tooltip.Trigger>
<Tooltip.Content>
Search domains and invoices
<Kbd>⌘K</Kbd>
</Tooltip.Content>
</Tooltip.Root>
</Tooltip.Provider>Explain a disabled button
Disabled buttons get no pointer or focus events. Wrap the button in a focusable span and put the trigger props on it.
<script lang="ts">
import * as Tooltip from '@statix/ui/tooltip';
import { Button } from '@statix/ui/button';
import RotateCcwIcon from '@lucide/svelte/icons/rotate-ccw';
</script>
<Tooltip.Provider>
<Tooltip.Root>
<Tooltip.Trigger>
{#snippet child({ props })}
<!-- A disabled button gets no pointer or focus events, so the wrapper takes them. -->
<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
<span {...props} tabindex="0" class="inline-flex rounded-full">
<Button disabled>
<RotateCcwIcon data-icon="inline-start" />
Restore website
</Button>
</span>
{/snippet}
</Tooltip.Trigger>
<Tooltip.Content>Available after the first backup tonight at 03:10</Tooltip.Content>
</Tooltip.Root>
</Tooltip.Provider>Guidelines
Do
- Keep it to one short line. Up to 320px wide, then it wraps.
- Wrap a group of tooltips in one Tooltip.Provider so moving between them feels instant.
- Give every icon button an aria-label as well. The tooltip does not replace it.
Don't
- Don’t put links or buttons inside a tooltip. Use Popover.
- Don’t hide information people need to finish a task in a tooltip. Touch screens never show it.
Accessibility
- Opens on hover and on keyboard focus, closes on Escape, blur or pointer leave.
- The content has role="tooltip" and the trigger points to it with aria-describedby while it is open.
- Touch devices do not show tooltips. Do not rely on them for essential information.
API reference
Tooltip.Provider
Shares delay settings between tooltips. Wrap a toolbar or the whole app in one.
| Prop | Type | Default |
|---|---|---|
delayDuration | number Milliseconds before a tooltip opens. | 0 |
skipDelayDuration | number Time window in which the next tooltip opens without delay. | 300 |
disableHoverableContent | boolean Closes the tooltip as soon as the pointer leaves the trigger. | false |
Tooltip.Root
One tooltip. Renders no element.
| Prop | Type | Default |
|---|---|---|
open bind | boolean Whether the tooltip is shown. | false |
delayDuration | number Overrides the provider delay for this tooltip. | – |
Tooltip.Trigger
renders<button> and accepts its attributesThe element the tooltip describes. Use the child snippet to render a Button.
| Data attribute | Meaning |
|---|---|
data-state | "closed", "delayed-open" or "instant-open". |
Tooltip.Content
renders<div role="tooltip"> and accepts its attributesThe label: ink background, white 13.5px text, 10px radius, with an arrow.
| Prop | Type | Default |
|---|---|---|
side | 'top' | 'right' | 'bottom' | 'left' Preferred side. | 'top' |
sideOffset | number Gap to the trigger in pixels. | 4 |
align | 'start' | 'center' | 'end' Alignment against the trigger. | 'center' |
arrowClasses | string Extra classes for the arrow, for example to recolour it with the content. | – |
portalProps | Tooltip.PortalProps Props for the portal. | – |
class | ClassValue Merged with the content classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="tooltip-content" | Always present. |
data-side | The side it ended up on. |