HyTooltip

A lightweight tooltip component that displays contextual information when hovering or focusing on an element.

Trigger Patterns

Slotted trigger (preferred for client-side apps): The trigger element is passed via the trigger slot, ensuring ARIA relationships work correctly across shadow DOM boundaries.

for attribute (fallback for SSR frameworks): For SSR frameworks like Next.js, Nuxt, or SvelteKit, use the for attribute to reference a trigger element by ID. This avoids hydration timing issues with the slotchange event.

Key Features

• Automatic positioning with Floating UI
• Configurable show/hide delays
• Hover, focus, or combined triggers
• Dismissible, hoverable, and persistent
• Full keyboard support (Escape to dismiss)
• SSR-compatible via for attribute fallback

Accessibility

• Automatic aria-describedby on the trigger element
• role="tooltip" for screen readers
• Focus stays on trigger (tooltips never steal focus)

Examples

Basic Usage (Slotted Trigger)

<hy-tooltip>
  <button slot="trigger">Save</button>
  Save your changes
</hy-tooltip>

SSR Framework Usage (for attribute)

<button id="save-btn">Save</button> <hy-tooltip for="save-btn">Save your changes</hy-tooltip>

With Placement

<hy-tooltip placement="bottom">
  <button slot="trigger">?</button>
  Click for help
</hy-tooltip>

Hover Only

<hy-tooltip trigger="hover">
  <span slot="trigger" tabindex="0">API</span>
  Application Programming Interface
</hy-tooltip>

Custom Delay

<hy-tooltip delay="500">
  <button slot="trigger">Delete</button>
  This cannot be undone
</hy-tooltip>

Note: show / hide are dispatched with bubbles: false. A tooltip's visibility is a purely local concern (no parent-coordination protocol like menubar↔menu-item), and a bubbling composed hide would collide with an ancestor overlay's same-named handler — e.g. a tooltip inside an hy-dialog would trip the dialog's onhide and close the modal. Listen directly on the <hy-tooltip> element (onshow / onhide) — target-phase delivery is unaffected. Matches the React mirror, whose onShow / onHide are callbacks

## Events

- **show** - Fired after the tooltip opens (does NOT bubble). Detail: `{ source: 'hover' | 'focus' | 'programmatic' }`
- **hide** - Fired after the tooltip closes (does NOT bubble). Detail: `{ source: 'hover' | 'focus' | 'escape-key' | 'programmatic' }`

## Slots

- **trigger** - The element that triggers the tooltip (required)
- **default** - The tooltip content

## Methods

### willUpdate()

Generates unique IDs before the first render and handles state changes
that would otherwise trigger update-after-update warnings.

### show()

Shows the tooltip programmatically.

### hide()

Hides the tooltip programmatically.