Tooltip

A short label that appears when its trigger is hovered or focused. It stands centred above its control, two pixels clear, and never leaves the window: near an edge it moves to stand four pixels inside it, and with no room above it stands below (or above, with placement="bottom" and no room below).

Design examples

A labelled editing toolbar

Example Code

Focus or hover the compact controls to read their full action names.

Try it

Hover or focus

Example Code

The label starts visible. Hover over the button, or focus it with Tab to try it.

A translated label with a fallback

Example Code

Hover or focus to see the fallback when the key has no translation.

When to use it

Use a tooltip to clarify a compact control. Keep essential instructions visible on the page: someone on a touch screen may never hover. Put a focusable button or link inside the wrapper so keyboard users can reveal the label too.

Attributes

Attribute	Type	Default	What it does
text	string	Empty	A translation key or literal label.
default-value	string	Empty	Fallback when the key has no translation.

Behaviour

The label appears above the trigger on hover or focus and disappears on mouse leave or focus leaving the trigger. position is not a supported attribute: the component always places its label above the trigger.

Many tooltips on one page

For a collection of controls, the shared tooltip module also supports data-tooltip="Save changes". Import DS1/0-face/tooltips.ts once; it draws a shared label for those elements, including marked elements inside a component’s open shadow root, as the Sidebar marks its cut-short labels. Mark only what the label adds to: a cut-short or icon-only control, never every row.

The shared label:

• shows at once on hover with a mouse or pen;
• shows on focus only when the focus is the keyboard’s (:focus-visible), so a menu that moves focus into its first row on a press does not raise one;
• follows its element’s data-tooltip (and data-tooltip-colour) while it shows, so a play button that turns into a pause button says so, and goes when the text does;
• on touch, shows from a long press (half a second), and the click that releasing the finger makes is held back; an element marked data-tooltip-press shows it from a tap as well, and still gets its click. A touch label goes at the next touch or after two seconds, and a finger that moves is scrolling, not pressing.

From code, showTooltip(element) shows an element’s label as a press would, until hideTooltip(); showTooltip(element, { duration: 2000 }) hides it after that many milliseconds.

<button data-tooltip="Size 40" data-tooltip-press>40</button>

import { showTooltip, hideTooltip } from './ds1/0-face/tooltips';

showTooltip(button, { duration: 2000 });

Sync 1’s root export copies the module with "modules": ["tooltips"].

Related components

Button provides a focusable trigger. Icon supplies a compact drawing. Languages explains translation keys.