Skip to content
Statix Design System

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

Controls
<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.

PropTypeDefault
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.

PropTypeDefault
open bindboolean

Whether the tooltip is shown.

false
delayDuration number

Overrides the provider delay for this tooltip.

–

Tooltip.Trigger

renders <button> and accepts its attributes

The element the tooltip describes. Use the child snippet to render a Button.

Data attributeMeaning
data-state"closed", "delayed-open" or "instant-open".

Tooltip.Content

renders <div role="tooltip"> and accepts its attributes

The label: ink background, white 13.5px text, 10px radius, with an arrow.

PropTypeDefault
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 attributeMeaning
data-slot="tooltip-content"Always present.
data-sideThe side it ended up on.