Holo Tooltip

The <holo-tooltip> component shows a short, non-interactive hint for a trigger element referenced by its id via the for prop. It uses the Popover API (popover="manual" + showPopover()/hidePopover()) triggered on the referenced element’s hover/focus, is linked to the trigger via aria-describedby, and is hidden on blur/mouseleave/Esc.

Positioning note: CSS anchor positioning (anchor-name/position-anchor) is not yet broadly supported across engines, so this component falls back to getBoundingClientRect()-based fixed positioning rather than relying on anchor positioning alone.

Why for instead of a trigger slot? Referencing the trigger by id keeps the trigger element in its natural place in the light DOM (so it isn’t affected by the tooltip’s own layout) and makes the aria-describedby wiring straightforward and explicit.

When to use

Use it for:

• A short text hint that names or explains a control, such as an icon-only button.
• Supplementary information that is not needed to complete the task.

Don’t use it for:

• Essential information or instructions. Show them as visible text.
• Interactive content, links or formatting. Use Popover.
• Errors or validation messages. Use an Alert or field error text.
• Touch-only interfaces, where there is no hover or focus.

Live Previews

Placements

TopHelpful hint textBottomHelpful hint text

<button id="trigger">Hover or focus me</button> <holo-tooltip for="trigger" placement="top">Helpful hint text</holo-tooltip>

Accessibility

The tooltip is a <div role="tooltip" popover="manual"> in the shadow root. It finds its trigger from the for prop (the trigger’s id), looked up in the tooltip’s own tree: the document, or the shadow root the tooltip is in. It sets aria-describedby on the trigger pointing at the <holo-tooltip> element (which gets a generated id if it has none), so the tooltip text is read as the trigger’s description. The host is aria-hidden="true": the text is still used as the description, but it is not read a second time as page content.

It is shown when the trigger is hovered or receives focus. It stays open while the pointer is over the trigger or the tooltip, or the trigger has focus, and hides shortly after none of these is true.

Key	Action
Tab	Focusing the trigger shows the tooltip. Moving away hides it
Esc	Hides the tooltip while it is visible

• Because it is described, not named, the tooltip never replaces an accessible name.
• You can move the pointer from the trigger onto the tooltip without it closing (WCAG 1.4.13). The tooltip does not take focus.
• The fade only runs when prefers-reduced-motion: no-preference.

You provide:

• A focusable trigger with an id, in the same document or shadow root as the tooltip. Use a native <button> or <a>: Button does not forward aria-describedby to its inner button.
• An accessible name on the trigger. Do not rely on the tooltip for an icon button’s name.
• Hint text that is short and non-essential.

---

API Reference

Importing

import '@philbob-sideprojects/hololink-ui/holo-tooltip';

Properties

Property	Attribute	Type	Default	Description
for (required)	for	string	—	The id of the trigger element that this tooltip describes. The trigger must be in the same document or shadow root as the tooltip. The tooltip is shown on the trigger's hover/focus and hidden on blur/mouseleave/Esc, and is linked to it via aria-describedby.
placement	placement	"bottom" | "end" | "start" | "top"	'top'	Which side of the trigger the tooltip is positioned on.

Slots

Slot	Description
(default)	The tooltip text.

CSS custom properties

Property	Description
--holo-tooltip-bg	Background color of the tooltip.
--holo-tooltip-padding	Inner padding of the tooltip.
--holo-tooltip-radius	Corner radius of the tooltip.
--holo-tooltip-shadow	Box shadow of the tooltip.
--holo-tooltip-text-color	Text color of the tooltip.