Tooltip pattern

Tooltip

Tooltips reuse the toggle foundation but add hover intent, long-press support, and placement helpers. Like dialogs, the context syntax and alias produce identical behavior. Review the Contexts guide to understand how tooltip capabilities fit into the broader registry alongside menus, accordions, and other planned composites.

Behavior highlights

• Synchronizes aria-describedby between trigger and tooltip.
• Keeps tooltips hidden by default and toggles hidden + aria-hidden.
• Supports pointer hover, focus, keyboard, and long-press activation.
• Shares truthiness mapping for class hooks, so data-automagica11y-trigger-class-shown just works.
• Emits context events (automagica11y:tooltip:toggle, automagica11y:tooltip:shown, automagica11y:tooltip:hidden) whenever the tooltip visibility changes.

Attribute reference

Attribute reference

Attribute	Type	Allowed values	Default	Description
data-automagica11y-context="tooltip"	string	`tooltip`	N/A	Activates tooltip semantics and behaviors.
data-automagica11y-tooltip	string | Selector	CSS selector or ID reference	None	Legacy alias mapped to the tooltip context.
data-automagica11y-target	string | Selector	CSS selector or ID reference	Next sibling	Explicitly points at the tooltip surface when using context syntax.
data-automagica11y-tooltip-open-delay	number (ms)	0+	0	Delay before showing the tooltip after hover/focus.
data-automagica11y-tooltip-close-delay	number (ms)	0+	100	Delay before hiding once the pointer/focus leaves.
data-automagica11y-tooltip-position	`auto` | `top` | `bottom` | `left` | `right`	Placement tokens	`auto`	Preferred placement; flips automatically when space is tight.

Alias fidelity

Alias compatibility

data-automagica11y-tooltip is implemented on top of the tooltip context. Switching syntax will not change runtime behavior.

Events

Event	Detail payload
automagica11y:tooltip:ready	{ trigger, target } when hydration finishes.
automagica11y:tooltip:toggle	{ trigger, target, expanded } every time the tooltip state flips.
automagica11y:tooltip:shown / hidden	{ trigger, target } after visibility changes settle.

Demo

Tooltip interactions

Hover, focus, or long-press to show hints.

View source

Context trigger

Alias trigger

Coverage plan

1. Add a demo illustrating hover intent configuration with different open/close delays.
2. Document how tooltips respond to touch long-press and how to customize data-automagica11y-tooltip-long-press.
3. Provide guidance for accessible dismiss buttons using data-automagica11y-tooltip-dismiss.

See the Examples roadmap for progress tracking.