Components
Tooltip
A two-to-four-word hint that names an icon button for pointer and keyboard users. It never carries the only name.
import * as Tooltip from "@sideby/ui/tooltip";
import { buttonVariants } from "@sideby/ui/button";
import Link from "@lucide/svelte/icons/link";
<Tooltip.Root delayDuration={150}>
<Tooltip.Trigger class={buttonVariants({ variant: "outline", size: "icon" })} aria-label="Copy link">
<Link aria-hidden="true" />
</Tooltip.Trigger>
<Tooltip.Content>Copy link</Tooltip.Content>
</Tooltip.Root> When to use it
Use a tooltip to name an icon-only button for people with a mouse or a keyboard: a player toolbar, a copy button, a mute button. It is a supplementary hint, never the only way to learn what a control does.
- The button names itself. Every icon button carries an
aria-label. The tooltip repeats those words for people who can see the pointer or the focus ring. - Never put essential information in a tooltip. Tooltips do not open on touch screens, so anything a phone user needs belongs in the page.
- Never put interactive content in one. No links, no buttons. Use a dialog or a menu instead.
A toolbar
Once one tooltip is open, its neighbours open at once, so moving along a toolbar reads like a list of names.
import { buttonVariants } from "@sideby/ui/button";
import * as Tooltip from "@sideby/ui/tooltip";
<div role="toolbar" aria-label="Player" class="flex gap-2">
{#each toolbar as item}
<Tooltip.Root>
<Tooltip.Trigger class={buttonVariants({ variant: "ghost", size: "icon" })} aria-label={item.label}>
<item.icon aria-hidden="true" />
</Tooltip.Trigger>
<Tooltip.Content>{item.label}</Tooltip.Content>
</Tooltip.Root>
{/each}
</div> Setup
Mount one Tooltip.Provider around the app, in the root layout. It sets the shared delay (400ms by default). A Tooltip.Root can override it with delayDuration.
<!-- src/routes/+layout.svelte -->
<script lang="ts">
import * as Tooltip from "@sideby/ui/tooltip";
let { children } = $props();
</script>
<Tooltip.Provider>
{@render children()}
</Tooltip.Provider> The skin
An inverted chip: the foreground color as the fill and the background color as the text, so it stands out in both themes. It is flat, with no arrow, and it fades in at the fast motion duration. Under reduced motion it simply appears.
Keyboard
- Tab to the button opens its tooltip after the delay, the same as hovering over it.
- Escape closes the tooltip and keeps focus on the button.
- Moving focus or the pointer away closes it.
Accessibility
- Bits UI owns the behaviour: the
tooltiprole, the delay, Escape, and thearia-describedbylink from the button to the open tooltip. - It opens on hover and on keyboard focus, never on touch. That is why every icon button needs its own
aria-label; on a phone the label is the only name it has. - Screen readers announce the button’s label, then the tooltip as its description. Keep the two the same, so nothing new hides in the tooltip.
Copy
- Two to four words. “Copy link”, “Mute”, “Full screen”.
- Name the action, not the icon. “Copy link”, not “Chain icon”.
- Sentence case, no full stop, and the same words as the button’s
aria-label.