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’saria-describedbynames the label. openis 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.
Anatomy
Section titled “Anatomy”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
<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>Two-way binding
Section titled “Two-way binding”bind:open on the root. The value follows hover, focus, and Escape.
open: false
Code
<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>Fully controlled
Section titled “Fully controlled”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
<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>Icon trigger
Section titled “Icon trigger”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
<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 and states
Section titled “Placement and states”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
Styling
Section titled “Styling”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 |
Keyboard
Section titled “Keyboard”| Key | Action |
|---|---|
| Tab | Moves focus to the control inside the trigger and opens the tooltip. |
| Escape | Closes the tooltip. Focus stays on the control. |
Tabbing away from the control closes the tooltip. The trigger span is never a tab stop.
| Prop | Type | Default | Description |
|---|---|---|---|
bind:open | boolean | Whether the tooltip is showing. Two-way bindable. | |
openDelay | number | 300 | Milliseconds the pointer rests on the trigger before the tooltip opens. |
disabled | boolean | false | Keep the tooltip from opening. |
interactive | boolean | false | Keep 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. |
children | Snippet | The 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.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | `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. |
sideOffset | number | 4 | Gap in pixels between the trigger and the label. |
portal | PortalTarget | true | Where 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>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. |
Plus everything in HTMLAttributes<HTMLSpanElement>, spread onto the element.