Contents

Components

Tooltip

A two-to-four-word hint that names an icon button for pointer and keyboard users. It never carries the only name.

Props
side
delay
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.

Player toolbar
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 tooltip role, the delay, Escape, and the aria-describedby link 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.