Tooltip
import "@taprootio/espalier/tooltip";
<esp-tooltip>
A lightweight tooltip wrapper around esp-popover that
provides ARIA tooltip semantics and sensible defaults for
hover/focus-triggered contextual help.
The simplest usage provides a text property for plain-text
content. For rich HTML, nest a <template> element inside the
tooltip — its content will be cloned into the tooltip bubble.
Tooltips also work on inline text elements like abbreviations:
For richer content, use a <template> child. Because
<template> is phrasing content, it works safely inside
<p> elements — block-level elements like <div> inside
the template won't break the surrounding DOM:
When wrapping an already-focusable control (a <button> or
<esp-button>), the tooltip automatically takes its wrapper span out of
the tab order so it does not add a second, redundant tab stop. The
control itself stays naturally focusable — only the wrapper span leaves
the tab order. Hover still reveals the tooltip, and the tooltip's
aria-describedby is mirrored onto the control so it is still announced
on focus. No extra attribute is needed:
Set trigger-tabindex explicitly only to override that auto-detection
(see the property docs below).
Inside a roving-tabindex toolbar (for example esp-button-group in
toolbar mode), the toolbar manager owns each button's own tabindex
(one 0, the rest -1, arrow keys move between them) and sets
trigger-tabindex="-1" on each direct esp-tooltip child for you, so the
tooltip wrapper does not reintroduce the extra tab stops the roving
manager is removing.
Slots
<esp-tooltip> has a slot:
Default
The trigger element (icon, term, abbreviation, etc.).
Attributes
<esp-tooltip> has the following attributes:
text
text has a default value of "".
Plain-text content to display in the tooltip. For richer
HTML, use a <template> child element instead.
attach
attach has a default value of "above".
Which side of the trigger the tooltip appears on.
align
align has a default value of "center".
How the tooltip is aligned relative to the trigger.
offset
offset has a default value of "4px".
Distance between the trigger and the tooltip.
show-delay
show-delay has a default value of 300.
Delay in milliseconds before showing the tooltip.
hide-delay
hide-delay has a default value of 100.
Delay in milliseconds before hiding the tooltip.
trigger-tabindex
trigger-tabindex has a default value of undefined.
Tabindex applied to the tooltip trigger span.
Leave it unset to get the right default automatically: a tooltip
wrapping a focusable button (<button> or <esp-button>) takes its
wrapper span out of the tab order (-1) so it does not add a second,
redundant tab stop, while a tooltip wrapping non-interactive content
(an icon, an abbreviation, plain text) keeps the wrapper focusable
(0) so keyboard users can still reveal it on focus.
Set it explicitly to override that auto-detection — for example
trigger-tabindex="0" to force a focusable wrapper, or
trigger-tabindex="-1" to opt a non-button trigger out. An explicit
value always wins; a non-numeric or NaN value falls back to 0.
When the wrapper leaves the tab order, keyboard focus lands on the
slotted control instead, so the tooltip's aria-describedby is
mirrored onto that control and assistive tech still announces the
description on focus.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-tooltip> has the following methods:
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
CSS Properties
<esp-tooltip> has the following CSS properties:
--esp-tooltip-background
Background color of the tooltip. Defaults to var(--esp-color-layer-1).
--esp-tooltip-color
Text color inside the tooltip. Defaults to var(--esp-color-text).
--esp-tooltip-border
Border of the tooltip. Defaults to 1px solid var(--esp-color-border).
--esp-tooltip-border-radius
Border radius of the tooltip. Defaults to var(--esp-size-border-radius).
--esp-tooltip-padding
Padding inside the tooltip. Defaults to var(--esp-size-tiny) var(--esp-size-small).
--esp-tooltip-font-size
Font size of tooltip text. Defaults to var(--esp-type-small).
--esp-tooltip-max-width
Maximum width of the tooltip. Defaults to 40ch.
--esp-tooltip-shadow
Box shadow for the tooltip. Defaults to 2px 2px 4px var(--esp-color-shadow).
--esp-tooltip-focus-outline
Outline used when the trigger receives keyboard focus. Defaults to 2px solid var(--esp-color-link).
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).