Tooltip

Code

Copy the markup

<div class="luz-tooltip">
  <button class="luz-btn luz-btn--outline" type="button" aria-describedby="archive-tip">Archive</button>
  <div class="luz-tooltip__text" role="tooltip" id="archive-tip">Hides the project from the list</div>
</div>

Variants and options

One position: above the control, centred. Where the browser has CSS anchor positioning, the tip moves below the control when there is no room above.

There are no modifiers.

How it works

CSS only, from components/tooltip.css: the tip shows while the wrapper is hovered or holds focus.

• It stays open while the pointer moves from the control onto the tip.
• It fades in and out over --luz-duration-fast, and appears at once under reduced motion.
• The tip does not wrap: keep it short, or it can overflow a narrow screen.
• Enhancement: in browsers with CSS anchor positioning (Chrome and Edge 125, Safari 26, Firefox 147: Newly available, not yet Widely available), the tip is anchored to its own control (anchor-scope and anchor() insets) and flips below it when there is no room above. Outside a size container it is no longer clipped by an ancestor that hides overflow; inside one, such as a table wrapper or a player, it is placed and clipped by that box, as before. In other browsers it stays above, as before: the rules sit inside @supports, with no script.

Without JavaScript

Nothing changes: the tooltip has no script.

Keyboard and ARIA

Focus the control with Tab and the tip shows; move the focus away and it hides.

• aria-describedby on the control points at the tip, so screen readers read it after the control's name.
• The tip has role="tooltip" and never takes focus.
• The control keeps its own name: the tip is a description, not a label.

Contrast and focus are in the Design tab.

Design

When to use

Use a tooltip to add a short explanation to a control whose label is clear but brief.

When not to use

Do not put anything essential, long or interactive in a tooltip.

• Touch screens have no hover: put information people need on the page, as a hint (form fields).
• Never use a tooltip as the only name of an icon button.
• No links or buttons inside it.

Do and don't

Writing the content

One short phrase that says what the control does or why: "Hides the project from the list".

• Do not repeat the control's label.
• No full stop on a fragment.

Contrast and focus

The tooltip is primary text on the strong surface, with a border and a shadow.

Measured from the token values of each mode, rounded down. Needs is the WCAG 2.2 AA minimum: 4.5:1 for text, 3:1 for focus rings, borders and icons.

• Focus: the tooltip shows when its control has focus, not only on hover; the ring is the control's own.
• Edges: a border and a shadow keep it apart from what is under it, in forced colors too.

Tokens it uses

The 11 tokens that components/tooltip.css reads, by family. Each family links to its page, with the values in every mode. In Figma they are variables with the same names: see Tokens in Figma.

Color

--luz-divider, --luz-surface-strong, --luz-text-primary

Spacing and sizing

--luz-space-2xs, --luz-space-xs

Typography

--luz-font-sans, --luz-text-sm

Radius

--luz-radius-md

Shadows

--luz-shadow-md

Motion

--luz-duration-fast

Layers

--luz-z-raised

Keyboard and ARIA are in the Code tab.