Tooltip

Provide a short supplemental description on focus or hover.

<hui-tooltip>View source View spec

Interactive

Try it

placement

Markup

State

Events

<hui-tooltip id="playground-tooltip" delay-duration="0" placement="bottom">
  <hui-tooltip-trigger>Passkeys</hui-tooltip-trigger>
  <hui-tooltip-content>Passkeys use your device unlock method.</hui-tooltip-content>
</hui-tooltip>

data-state: Waiting for enhancement

No component events yet.

Usage

Use hui-tooltip to provide a short, supplemental description for a focusable trigger. The trigger remains the accessible name source; aria-describedby is attached only while the tooltip is visible so hidden content never creates a dangling reference. Tooltip content is non-interactive and never traps focus.

Anatomy

Root: hui-tooltip
Trigger: hui-tooltip-trigger renders a native button
Content: hui-tooltip-content renders a role="tooltip" region when enhanced
State hooks: root, trigger, and content use data-state="visible|hidden"
Placement hook: content uses data-placement="top|bottom|left|right"

Examples

Fixture exampleSource-backed

<section aria-labelledby="tooltip-heading">
    <h2 id="tooltip-heading">Help</h2>
    <hui-tooltip id="help-tooltip" delay-duration="0" placement="bottom">
      <hui-tooltip-trigger><b>Passkeys</b></hui-tooltip-trigger>
      <hui-tooltip-content>Passkeys use your device unlock method.</hui-tooltip-content>
    </hui-tooltip>
    <hui-tooltip id="flip-tooltip" delay-duration="0" placement="top">
      <hui-tooltip-trigger>Placement</hui-tooltip-trigger>
      <hui-tooltip-content>This tooltip flips when there is not enough space.</hui-tooltip-content>
    </hui-tooltip>
  </section>

API reference

Root attributes

Attribute	Meaning
`delay-duration`	Delay in milliseconds before focus/hover reveals the tooltip. Defaults to `700`.
`placement`	Preferred placement: `top`, `bottom` (default), `left`, or `right`. Collision handling may choose another side.
`data-state`	Enhanced state: `visible` or `hidden`; normally managed by the component.

Events:

hui-visible-change: emitted by the root with { visible: boolean }.

States and styling

State	Contract and styling guidance
Hidden	Content has `hidden` after any allowed exit; trigger has no generated `aria-describedby`.
Visible	Content has `role="tooltip"`, a deterministic `id` when the root has an `id`, and the trigger references it with `aria-describedby`.
Focus	Trigger keeps a visible focus ring using `--hui-color-focus-ring`.
Touch	First touch reveals the tooltip; second touch is allowed through to activate the trigger.

State channel

Attributes are the source of truth. Style derived state with data-state, ARIA attributes, and the --hui-* token aliases.

Accessibility and keyboard support

Focus and mouse enter schedule reveal after delay-duration.
Blur and mouse leave hide the tooltip when no other trigger state keeps it open.
Escape hides the tooltip and latches it closed until the trigger is focused or hovered again.
Tooltip content is pointer-events: none and is never focusable.
A shared document delay group skips the reveal delay when moving between tooltips shortly after one opened.
Placement uses collision-aware positioning and writes --hui-position-x and --hui-position-y.

With motion allowed, a hidden tooltip keeps its positioned surface until the tokenized exit completes, while aria-describedby is removed immediately. The surface becomes hidden at completion; reduced-motion and no-transition paths complete immediately.

SSR and forms

Tooltip enhancement is client-only. SSR emits the projected trigger/content text without a button, role="tooltip", or aria-describedby; content is hidden so the server response has no dangling ARIA reference or visible popup. Client adoption re-renders the trigger and content templates while preserving projected node identity. Without JavaScript, the tooltip is inert by design.

Code

<hui-tooltip id="help-tooltip" delay-duration="200">
  <hui-tooltip-trigger>What is a passkey?</hui-tooltip-trigger>
  <hui-tooltip-content>
    A passkey lets you sign in with your device unlock method.
  </hui-tooltip-content>
</hui-tooltip>

<hui-tooltip id="playground-tooltip" delay-duration="0" placement="bottom">
  <hui-tooltip-trigger>Passkeys</hui-tooltip-trigger>
  <hui-tooltip-content>Passkeys use your device unlock method.</hui-tooltip-content>
</hui-tooltip>