Tooltip
A hover/focus hint that floats a short description beside its trigger, on any of four sides.
Live demo
Tooltip wraps an interactive trigger and surfaces a short, supplementary hint on hover and on keyboard focus. The hint is linked to the trigger with aria-describedby so assistive tech announces it as the element's description, and it floats to one of four placement sides (top, bottom, left, right) over an elevated overlay surface with a pointing arrow.
It satisfies WCAG 1.4.13 Content on Hover or Focus: the hint is dismissible with Escape, hoverable (the pointer can travel onto the tooltip without it vanishing), and persistent (it stays until focus leaves or the pointer departs both trigger and tooltip). Tip text comes from the text prop, or richer markup from the content slot. The hint scales past a one-line label: a mode of rich opens it into a roomier, left-aligned panel that wraps multi-line text and holds structured content — a detail card, a stat or progress readout — size dials the padding, and a tone colors it, as a leading edge over the neutral overlay by default or as a fully soft/solid toned surface.
When to use
How this component composes with the rest of the set.
Props
7 props, straight from the manifest.
| Prop | Type | Default | Bindings | Description |
|---|---|---|---|---|
Appearance
Variants
soft
With a tone, washes the whole hint in the tone's soft tint with a matching border and arrow.
solid
With a tone, fills the hint with the solid tone and its on-tone text and arrow.
Sizes
sm
Compact padding (the default).
md
Roomier padding.
States
open
Hint visible: fades in via the content's data-open flag while pointer or focus is on trigger or tooltip.
top
Hint floats above the trigger; arrow points down.
bottom
Hint floats below the trigger; arrow points up.
left
Hint floats to the left of the trigger; arrow points right.
right
Hint floats to the right of the trigger; arrow points left.
Anatomy
The named parts that make up the component, with their selectors.
tooltip
The inline wrapper around the trigger; carries the placement class and anchors the floating content.
content
The floating hint surface: an elevated overlay panel holding the tip text or content slot.
arrow
The rotated square nub pointing from the content back toward the trigger.
edge
The leading tone bar shown along the content's start edge when a tone is set without soft/solid; zero-width otherwise.
Tokens & coverage
What the component consumes, checked live against what the algorithm produces.
Live coverage check against the xoji-default register
(derive(xojiDefault, { anchors }) →
coverComponent(manifest, register)). Every token this component
consumes must be a key the algorithm produces.
--accent
--accent-2
--accent-2-bg
--accent-2-fg
--accent-2-text
--accent-3
--accent-3-bg
--accent-3-fg
--accent-3-text
--accent-4
--accent-4-bg
--accent-4-fg
--accent-4-text
--accent-bg
--accent-fg
--accent-text
--black
--black-bg
--black-fg
--black-text
--blue
--blue-bg
--blue-fg
--blue-text
--border-thin
--brown
--brown-bg
--brown-fg
--brown-text
--cyan
--cyan-bg
--cyan-fg
--cyan-text
--danger
--danger-bg
--danger-fg
--danger-text
--duration-fast
--ease-standard
--elevation-2
--fg-0
--font-sans
--gray
--gray-bg
--gray-fg
--gray-text
--green
--green-bg
--green-fg
--green-text
--info
--info-bg
--info-fg
--info-text
--leading-normal
--leading-tight
--neutral
--neutral-bg
--neutral-fg
--neutral-text
--orange
--orange-bg
--orange-fg
--orange-text
--pink
--pink-bg
--pink-fg
--pink-text
--purple
--purple-bg
--purple-fg
--purple-text
--radius-sm
--red
--red-bg
--red-fg
--red-text
--space-1
--space-2
--space-3
--space-8
--success
--success-bg
--success-fg
--success-text
--surface-overlay
--surface-overlay-border
--text-sm
--warn
--warn-bg
--warn-fg
--warn-text
--weight-normal
--white
--white-bg
--white-fg
--white-text
--yellow
--yellow-bg
--yellow-fg
--yellow-text
Slots
The trigger element the tooltip describes.
Rich hint markup, used in place of the text prop.
Accessibility
role="tooltip" and is linked to the trigger via aria-describedby, so it is announced as the trigger's description. aria-hidden); the binding warns at runtime when neither text nor a content slot is supplied. Code
Placement and rich content
A plain-text hint above a button, and a rich-markup hint to the right of an icon button.
<xoji-tooltip text="Save your changes" placement="top">
<button class="xoji-button xoji-button--solid xoji-button--accent">Save</button>
</xoji-tooltip>
<xoji-tooltip placement="right">
<button class="xoji-button xoji-button--outline xoji-button--neutral" aria-label="Settings">
<svg slot="icon-start" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path fill="currentColor" d="M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8Z" />
</svg>
</button>
<span slot="content">Open <strong>settings</strong></span>
</xoji-tooltip><script lang="ts">
import { Tooltip, Button } from "@xoji/svelte";
</script>
<Tooltip text="Save your changes" placement="top">
<Button variant="solid" tone="accent">Save</Button>
</Tooltip>
<Tooltip placement="right">
<Button variant="outline" tone="neutral" iconOnly ariaLabel="Settings">
{#snippet iconStart()}
<svg viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path fill="currentColor" d="M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8Z" />
</svg>
{/snippet}
</Button>
{#snippet content()}Open <strong>settings</strong>{/snippet}
</Tooltip>---
import { Tooltip, Button } from "@xoji/astro";
---
<Tooltip text="Save your changes" placement="top">
<Button variant="solid" tone="accent">Save</Button>
</Tooltip>
<Tooltip placement="right">
<Button variant="outline" tone="neutral" iconOnly aria-label="Settings">
<svg slot="icon-start" viewBox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path fill="currentColor" d="M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8Z" />
</svg>
</Button>
<span slot="content">Open <strong>settings</strong></span>
</Tooltip>