Skip to content

Tooltip

A tooltip: a short label that appears when its trigger is hovered or focused. Render Tooltip.Trigger around the control it describes and Tooltip.Content for the label.

Built on bits-ui Tooltip.

<Tooltip bind:open>
<Tooltip.Trigger>
<button type="button" aria-label="Copy">Copy</button>
</Tooltip.Trigger>
<Tooltip.Content>Copy to clipboard</Tooltip.Content>
</Tooltip>
  • Composed from three parts. The trigger wraps the control you already have, and the label floats beside it in a portal.
  • Opens when the pointer rests on the trigger for openDelay, or at once when the control inside takes keyboard focus. Closes on blur, on Escape, and when the pointer leaves.
  • The trigger is a <span>, never a button, so your control keeps its own role and tab stop. While the tooltip is open, that control’s aria-describedby names the label.
  • open is bindable. Bind it to read the state, or give it a getter and setter to decide when the tooltip may open.
  • The label flips to the opposite side when there is no room for placement.

Every part is a property on Tooltip. Tooltip renders no element of its own. Tooltip.Trigger wraps the control and Tooltip.Content is the label.

<Tooltip>
<Tooltip.Trigger>
<button type="button" aria-label="Copy">...</button>
</Tooltip.Trigger>
<Tooltip.Content>Copy to clipboard</Tooltip.Content>
</Tooltip>

A tooltip is a supplementary description. Give the control inside its own accessible name, as the aria-label above does, because a tooltip never replaces one.

Code
Basic.svelte
<script lang="ts">
import { mdiContentCopy } from "@mdi/js";
import { Icon, Tooltip } from "@viamrobotics/prime-ui";
</script>
<div class="not-content">
<Tooltip>
<Tooltip.Trigger class="inline-flex">
<button type="button" class="icon-button" aria-label="Copy">
<Icon icon={mdiContentCopy} />
</button>
</Tooltip.Trigger>
<Tooltip.Content>Copy to clipboard</Tooltip.Content>
</Tooltip>
</div>

bind:open on the root. The value follows hover, focus, and Escape.

open: false

Code
TwoWay.svelte
<script lang="ts">
import { mdiContentCopy } from "@mdi/js";
import { Icon, Tooltip } from "@viamrobotics/prime-ui";
let open = $state(false);
</script>
<div class="not-content">
<Tooltip bind:open>
<Tooltip.Trigger class="inline-flex">
<button type="button" class="icon-button" aria-label="Copy">
<Icon icon={mdiContentCopy} />
</button>
</Tooltip.Trigger>
<Tooltip.Content>Copy to clipboard</Tooltip.Content>
</Tooltip>
<p class="mt-3 text-sm text-subtle-2">open: <code>{open}</code></p>
</div>

Pass bind:open a getter and a setter. The setter runs on every attempt to open or close, and writing nothing vetoes it. State & binding explains both modes.

open: false

Code
Controlled.svelte
<script lang="ts">
import { mdiContentCopy } from "@mdi/js";
import { Checkbox, Field, Icon, Label, Tooltip } from "@viamrobotics/prime-ui";
let open = $state(false);
let isMuted = $state(false);
</script>
<div class="not-content flex flex-col gap-3">
<Tooltip
bind:open={
() => open,
(next) => {
if (!next || !isMuted) open = next;
}
}
>
<Tooltip.Trigger class="inline-flex">
<button type="button" class="icon-button" aria-label="Copy">
<Icon icon={mdiContentCopy} />
</button>
</Tooltip.Trigger>
<Tooltip.Content>Copy to clipboard</Tooltip.Content>
</Tooltip>
<Field class="flex items-center gap-2">
<Checkbox bind:checked={isMuted} />
<Label>Mute this tooltip</Label>
</Field>
<p class="text-sm text-subtle-2">open: <code>{open}</code></p>
</div>

An Icon is aria-hidden and not focusable, so a bare icon inside Tooltip.Trigger has no keyboard path and no accessible name. The tooltip then opens on hover only, and touch input does not open it either. That is not enough for a tooltip that tells the user something. To make an icon reachable, give it an aria-label and tabindex="0". The aria-label renders it as role="img" with a name, and the tabindex makes it the focusable element inside the trigger. Focusing it opens the tooltip, and while the tooltip is open the icon carries the aria-describedby.

Code
IconTrigger.svelte
<script lang="ts">
import { mdiInformationOutline } from "@mdi/js";
import { Icon, Tooltip } from "@viamrobotics/prime-ui";
</script>
<div class="not-content">
<Tooltip>
<Tooltip.Trigger class="inline-flex text-subtle-2">
<Icon
icon={mdiInformationOutline}
size="lg"
aria-label="About retries"
tabindex={0}
class="focus-ring"
/>
</Tooltip.Trigger>
<Tooltip.Content placement="right">Failed requests retry up to three times</Tooltip.Content>
</Tooltip>
</div>

placement on Tooltip.Content picks the side, and sideOffset sets the gap in pixels. interactive keeps the tooltip open while the pointer is over the label, so a link inside stays reachable. disabled keeps it from opening.

Placement

Disabled

Tooltip renders no element, so it takes no class. Tooltip.Trigger and Tooltip.Content take class on the element they render. The label has a dark background, white text-xs text, max-w-xs, and square corners, and it wears z-tooltip, the top layer; see z layers.

The trigger span is inline, so its box is a line box and not the control’s box. Pass class="inline-flex" to make the span fit an inline-flex control such as an icon-button, which centers the label on the control. bits-ui sets the data attributes in the table below.

Part Attribute Value
Trigger data-state closed, delayed-open, or instant-open
Trigger data-disabled present when disabled
Content data-state closed, delayed-open, or instant-open
Content data-side the resolved side of the trigger
Content data-align the resolved alignment
KeyAction
TabMoves focus to the control inside the trigger and opens the tooltip.
EscapeCloses the tooltip. Focus stays on the control.

Tabbing away from the control closes the tooltip. The trigger span is never a tab stop.

PropTypeDefaultDescription
bind:openbooleanWhether the tooltip is showing. Two-way bindable.
openDelaynumber300Milliseconds the pointer rests on the trigger before the tooltip opens.
disabledbooleanfalseKeep the tooltip from opening.
interactivebooleanfalseKeep the tooltip open while the pointer is over its content, so a link or button inside stays reachable. Otherwise it closes as the pointer leaves the trigger.
childrenSnippetThe Tooltip.* parts.

Tooltip.Content

The label of a Tooltip. It renders in a portal, positioned beside the trigger, and flips to the opposite side when there is no room.

PropTypeDefaultDescription
idstring`tooltip-${uid}`Element id. null is not accepted.
dir'ltr' | 'rtl'Text direction of the label. auto is not accepted, because positioning needs a concrete direction.
placement'top' | 'right' | 'bottom' | 'left''top'Which side of the trigger the label appears on.
sideOffsetnumber4Gap in pixels between the trigger and the label.
portalPortalTargettrueWhere the label renders: true at the end of <body>, false in place, or inside an element or the first match of a CSS selector.

Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.

Tooltip.Trigger

Wraps the control a Tooltip describes. It renders a <span> around its children, never a button, so the control inside keeps its own role and focus behavior.

Focusing the control inside opens the tooltip. While it is open, the control’s aria-describedby names the Tooltip.Content. A child with nothing focusable in it, such as an Icon, opens the tooltip on hover only. Give the icon an aria-label and tabindex="0" to make it reachable by keyboard.

Built on bits-ui Tooltip.

<Tooltip.Trigger>
<button type="button" aria-label="Copy">Copy</button>
</Tooltip.Trigger>
PropTypeDefaultDescription
idstringElement id. null is not accepted.

Plus everything in HTMLAttributes<HTMLSpanElement>, spread onto the element.