Hover Card

A preview of linked content shown on hover or keyboard focus.

bun add @data-slot/hover-card

npm install @data-slot/hover-card

pnpm add @data-slot/hover-card

Anatomy

A trigger and its content. The card opens on hover and on keyboard focus after a short delay, so keep the trigger focusable.

<div data-slot="hover-card">
  <button data-slot="hover-card-trigger">Trigger</button>
  <div data-slot="hover-card-content">Content</div>
</div>

Examples

Preview on hover

<div data-slot="hover-card" data-delay="180" data-close-delay="120" class="hover-card-root">
  <button data-slot="hover-card-trigger" class="hover-card-trigger-btn">@data-slot</button>
  <div data-slot="hover-card-content" data-side="bottom" data-align="start" class="hover-card-content" hidden>
    <div class="hover-card-head">
      <div class="hover-card-avatar">DS</div>
      <div>
        <p class="hover-card-title">data-slot</p>
        <p class="hover-card-handle">@data-slot</p>
      </div>
    </div>
    <p class="hover-card-text">Headless UI components for vanilla JavaScript.</p>
    <p class="hover-card-meta">Hover/focus to preview, leave to close.</p>
  </div>
</div>

<style>
  .hover-card-root { display: inline-block; }
  .hover-card-trigger-btn {
    padding: 0.5rem 0.875rem;
    background: none;
    border: 1px dashed var(--border);
    cursor: pointer;
    font-weight: 600;
  }
  .hover-card-content {
    position: fixed;
    width: 18rem;
    background: var(--surface);
    border: 1px solid var(--border);
    padding: 0.75rem;
    z-index: 50;
    transform-origin: var(--transform-origin, center);
    --hover-card-slide-x: 0px;
    --hover-card-slide-y: -4px;
    max-width: var(--available-width);
    box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  }
  .hover-card-content[data-side="top"] { --hover-card-slide-y: 4px; }
  .hover-card-content[data-side="bottom"] { --hover-card-slide-y: -4px; }
  .hover-card-content[data-side="left"] {
    --hover-card-slide-x: 4px;
    --hover-card-slide-y: 0px;
  }
  .hover-card-content[data-side="right"] {
    --hover-card-slide-x: -4px;
    --hover-card-slide-y: 0px;
  }
  .hover-card-content[data-open] {
    animation: hover-card-in 160ms cubic-bezier(0.16, 1, 0.3, 1);
  }
  .hover-card-content[data-closed] {
    pointer-events: none;
    animation: hover-card-out 120ms ease-in forwards;
  }
  .hover-card-content[data-instant] {
    transition: none;
    animation: none;
  }
  @keyframes hover-card-in {
    from {
      opacity: 0;
      scale: 0.96;
      translate: var(--hover-card-slide-x) var(--hover-card-slide-y);
    }
    to {
      opacity: 1;
      scale: 1;
      translate: 0 0;
    }
  }
  @keyframes hover-card-out {
    from {
      opacity: 1;
      scale: 1;
      translate: 0 0;
    }
    to {
      opacity: 0;
      scale: 0.96;
      translate: var(--hover-card-slide-x) var(--hover-card-slide-y);
    }
  }
  .hover-card-head {
    display: flex;
    align-items: center;
    gap: 0.625rem;
  }
  .hover-card-avatar {
    width: 2rem;
    height: 2rem;
    border-radius: 9999px;
    display: grid;
    place-items: center;
    background: var(--text);
    color: var(--bg);
    font-size: 0.75rem;
    font-weight: 700;
    line-height: 1rem;
  }
  .hover-card-title {
    font-weight: 700;
    margin: 0;
    line-height: 1.25;
  }
  .hover-card-handle {
    margin: 0;
    color: var(--muted);
    font-size: 0.75rem;
    line-height: 1rem;
  }
  .hover-card-text {
    margin: 0.75rem 0 0;
    font-size: 0.875rem;
    line-height: 1.25rem;
  }
  .hover-card-meta {
    margin: 0.25rem 0 0;
    font-size: 0.75rem;
    color: var(--muted);
    line-height: 1rem;
  }
</style>

<div data-slot="hover-card" data-delay="180" data-close-delay="120" class="inline-block">
  <button
    data-slot="hover-card-trigger"
    class="px-3.5 py-2 bg-transparent border border-dashed border-[var(--border)]
           cursor-pointer font-semibold hover:bg-code-bg transition-colors"
  >
    @data-slot
  </button>

  <div
    data-slot="hover-card-content"
    data-side="bottom"
    data-align="start"
    class="fixed w-72 max-w-(--available-width) bg-[var(--surface)] border border-[var(--border)]
           p-3 z-50 shadow-lg"
    hidden
  >
    <div class="flex items-center gap-2.5">
      <div class="w-8 h-8 rounded-full grid place-items-center bg-text text-bg text-xs font-bold">DS</div>
      <div>
        <p class="font-bold leading-tight">data-slot</p>
        <p class="text-[var(--muted)] text-xs">@data-slot</p>
      </div>
    </div>
    <p class="mt-3 text-sm">Headless UI components for vanilla JavaScript.</p>
    <p class="mt-1 text-xs text-[var(--muted)]">Hover/focus to preview, leave to close.</p>
  </div>
</div>

/* Animation hooks */
[data-slot="hover-card-content"] {
  transform-origin: var(--transform-origin, center);
  --hover-card-slide-x: 0px;
  --hover-card-slide-y: -4px;
}
[data-slot="hover-card-content"][data-side="top"] {
  --hover-card-slide-y: 4px;
}
[data-slot="hover-card-content"][data-side="bottom"] {
  --hover-card-slide-y: -4px;
}
[data-slot="hover-card-content"][data-side="left"] {
  --hover-card-slide-x: 4px;
  --hover-card-slide-y: 0px;
}
[data-slot="hover-card-content"][data-side="right"] {
  --hover-card-slide-x: -4px;
  --hover-card-slide-y: 0px;
}
[data-slot="hover-card-content"][data-open] {
  animation: hover-card-in 160ms cubic-bezier(0.16, 1, 0.3, 1);
}
[data-slot="hover-card-content"][data-closed] {
  pointer-events: none;
  animation: hover-card-out 120ms ease-in forwards;
}
[data-slot="hover-card-content"][data-instant] {
  transition: none;
  animation: none;
}

import { create } from "@data-slot/hover-card";

// Initialize after the markup is in the document.
const controllers = create();

// Clean up before removing the component.
// controllers.forEach((controller) => controller.destroy());

Position above the trigger

data-side="top" is a preference, not a rule — the card flips to stay in the viewport.

<div data-slot="hover-card" data-delay="180" data-close-delay="120" class="hover-card-root">
  <button data-slot="hover-card-trigger" class="hover-card-trigger-btn">@data-slot</button>
  <div data-slot="hover-card-content" data-side="top" data-align="start" class="hover-card-content" hidden>
    <div class="hover-card-head">
      <div class="hover-card-avatar">DS</div>
      <div>
        <p class="hover-card-title">data-slot</p>
        <p class="hover-card-handle">@data-slot</p>
      </div>
    </div>
    <p class="hover-card-text">Headless UI components for vanilla JavaScript.</p>
    <p class="hover-card-meta">Hover/focus to preview, leave to close.</p>
  </div>
</div>

<style>
  .hover-card-root { display: inline-block; }
  .hover-card-trigger-btn {
    padding: 0.5rem 0.875rem;
    background: none;
    border: 1px dashed var(--border);
    cursor: pointer;
    font-weight: 600;
  }
  .hover-card-content {
    position: fixed;
    width: 18rem;
    background: var(--surface);
    border: 1px solid var(--border);
    padding: 0.75rem;
    z-index: 50;
    transform-origin: var(--transform-origin, center);
    --hover-card-slide-x: 0px;
    --hover-card-slide-y: -4px;
    max-width: var(--available-width);
    box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  }
  .hover-card-content[data-side="top"] { --hover-card-slide-y: 4px; }
  .hover-card-content[data-side="bottom"] { --hover-card-slide-y: -4px; }
  .hover-card-content[data-side="left"] {
    --hover-card-slide-x: 4px;
    --hover-card-slide-y: 0px;
  }
  .hover-card-content[data-side="right"] {
    --hover-card-slide-x: -4px;
    --hover-card-slide-y: 0px;
  }
  .hover-card-content[data-open] {
    animation: hover-card-in 160ms cubic-bezier(0.16, 1, 0.3, 1);
  }
  .hover-card-content[data-closed] {
    pointer-events: none;
    animation: hover-card-out 120ms ease-in forwards;
  }
  .hover-card-content[data-instant] {
    transition: none;
    animation: none;
  }
  @keyframes hover-card-in {
    from {
      opacity: 0;
      scale: 0.96;
      translate: var(--hover-card-slide-x) var(--hover-card-slide-y);
    }
    to {
      opacity: 1;
      scale: 1;
      translate: 0 0;
    }
  }
  @keyframes hover-card-out {
    from {
      opacity: 1;
      scale: 1;
      translate: 0 0;
    }
    to {
      opacity: 0;
      scale: 0.96;
      translate: var(--hover-card-slide-x) var(--hover-card-slide-y);
    }
  }
  .hover-card-head {
    display: flex;
    align-items: center;
    gap: 0.625rem;
  }
  .hover-card-avatar {
    width: 2rem;
    height: 2rem;
    border-radius: 9999px;
    display: grid;
    place-items: center;
    background: var(--text);
    color: var(--bg);
    font-size: 0.75rem;
    font-weight: 700;
    line-height: 1rem;
  }
  .hover-card-title {
    font-weight: 700;
    margin: 0;
    line-height: 1.25;
  }
  .hover-card-handle {
    margin: 0;
    color: var(--muted);
    font-size: 0.75rem;
    line-height: 1rem;
  }
  .hover-card-text {
    margin: 0.75rem 0 0;
    font-size: 0.875rem;
    line-height: 1.25rem;
  }
  .hover-card-meta {
    margin: 0.25rem 0 0;
    font-size: 0.75rem;
    color: var(--muted);
    line-height: 1rem;
  }
</style>

<div data-slot="hover-card" data-delay="180" data-close-delay="120" class="inline-block">
  <button
    data-slot="hover-card-trigger"
    class="px-3.5 py-2 bg-transparent border border-dashed border-[var(--border)]
           cursor-pointer font-semibold hover:bg-code-bg transition-colors"
  >
    @data-slot
  </button>

  <div
    data-slot="hover-card-content" data-side="top"
   
    data-align="start"
    class="fixed w-72 max-w-(--available-width) bg-[var(--surface)] border border-[var(--border)]
           p-3 z-50 shadow-lg"
    hidden
  >
    <div class="flex items-center gap-2.5">
      <div class="w-8 h-8 rounded-full grid place-items-center bg-text text-bg text-xs font-bold">DS</div>
      <div>
        <p class="font-bold leading-tight">data-slot</p>
        <p class="text-[var(--muted)] text-xs">@data-slot</p>
      </div>
    </div>
    <p class="mt-3 text-sm">Headless UI components for vanilla JavaScript.</p>
    <p class="mt-1 text-xs text-[var(--muted)]">Hover/focus to preview, leave to close.</p>
  </div>
</div>

/* Animation hooks */
[data-slot="hover-card-content"] {
  transform-origin: var(--transform-origin, center);
  --hover-card-slide-x: 0px;
  --hover-card-slide-y: -4px;
}
[data-slot="hover-card-content"][data-side="top"] {
  --hover-card-slide-y: 4px;
}
[data-slot="hover-card-content"][data-side="bottom"] {
  --hover-card-slide-y: -4px;
}
[data-slot="hover-card-content"][data-side="left"] {
  --hover-card-slide-x: 4px;
  --hover-card-slide-y: 0px;
}
[data-slot="hover-card-content"][data-side="right"] {
  --hover-card-slide-x: -4px;
  --hover-card-slide-y: 0px;
}
[data-slot="hover-card-content"][data-open] {
  animation: hover-card-in 160ms cubic-bezier(0.16, 1, 0.3, 1);
}
[data-slot="hover-card-content"][data-closed] {
  pointer-events: none;
  animation: hover-card-out 120ms ease-in forwards;
}
[data-slot="hover-card-content"][data-instant] {
  transition: none;
  animation: none;
}

import { create } from "@data-slot/hover-card";

// Initialize after the markup is in the document.
const controllers = create();

// Clean up before removing the component.
// controllers.forEach((controller) => controller.destroy());

API reference

Initialization

create(scope?)

Auto-discover and bind all hover-card instances in a scope (defaults to document).

import { create } from "@data-slot/hover-card";

const controllers = create(); // Returns HoverCardController[]

createHoverCard(root, options?)

Create a controller for a specific element.

import { createHoverCard } from "@data-slot/hover-card";

const hoverCard = createHoverCard(element, {
  delay: 700,
  closeDelay: 300,
  side: "bottom",
  align: "center",
  portal: true,
  onOpenChange: (open) => console.log(open),
});

Slots

Runtime Slots

• hover-card - Root element that manages the open state and hover delays.
• hover-card-trigger - Required element that opens the card on hover or focus.
• hover-card-content - Required floating panel that displays the preview content.
• hover-card-positioner - Optional authored positioning wrapper around the content, reused instead of a generated wrapper.
• hover-card-portal - Optional authored portal wrapper that can contain the positioner and content.

Markup

<div data-slot="hover-card">
  <button data-slot="hover-card-trigger">Trigger</button>
  <div data-slot="hover-card-content">Content</div>
</div>

Composed Portal Markup (Optional)

<div data-slot="hover-card">
  <button data-slot="hover-card-trigger">Trigger</button>
  <div data-slot="hover-card-portal">
    <div data-slot="hover-card-positioner">
      <div data-slot="hover-card-content">Content</div>
    </div>
  </div>
</div>

Data Attributes

Options can be set via data attributes. JS options take precedence.

Placement attributes (data-side, data-align, data-side-offset, data-align-offset, data-avoid-collisions, data-collision-padding) resolve in this order:

1. JavaScript option
2. hover-card-content
3. hover-card-positioner
4. hover-card root (fallback)

Boolean attributes: present/"true" = true, "false" = false, absent = default.

Options

Controlled Mode

When open is provided, hover/focus/outside interactions emit onOpenChange but do not mutate internal state. Use controller setOpen(open) or the hover-card:set event to apply state.

Controller

Controller Destruction

destroy() permanently disposes the controller and hides any open surface without emitting an additional change event. Repeated destruction is safe; methods on the old controller become no-ops. Create a new controller on the same root to rebind it.

Content mounting and server rendering

By default, Hover Card removes its closed preview from the page’s DOM. This keeps pages with many hover cards smaller after initialization. The link or button that opens the card stays in the page.

Opening the card puts the same preview back into the page. Its state and event listeners are preserved. Closing waits for any exit animation to finish before removing it. If the card opens again during that animation, it stays in the page. Cards configured to start open stay in the page from initialization.

Most applications can use this default without any changes.

If your code needs to find or update content while the card is closed—for example, using querySelector—use eager mode to keep it in the DOM:

createHoverCard(root, { mountStrategy: "eager" });

You can also add data-mount-strategy="eager" to the Hover Card root. A JavaScript option takes precedence over the HTML attribute.

With the default lazy mode, DOM queries won’t find the closed preview. You can also keep a reference to its content element before initializing Hover Card and use that reference later.

Server rendering and pages without JavaScript

Lazy mounting does not reduce the HTML sent to the browser. The preview is still included in your HTML; Hover Card removes it from the DOM after JavaScript initializes if the card is closed.

Keep the preview’s initial markup hidden to prevent it briefly appearing before initialization. Make essential information and links available outside the card so people can still use the page without JavaScript. Neither lazy nor eager mode provides that fallback automatically.

Events

Outbound Events

• hover-card:change - emitted when open state changes or is requested in controlled mode.

root.addEventListener("hover-card:change", (e) => {
  const { open, reason, trigger, content } = (e as CustomEvent).detail;
});

reason is one of: "pointer" | "focus" | "blur" | "dismiss" | "api".

Focus opening is keyboard-intent based (Tab navigation). Programmatic focus (for example, dialog auto-focus on open) does not auto-open the hover-card. Hover opening is pointer-intent based (recent mouse movement). Synthetic pointerenter caused by newly shown UI under a static cursor does not auto-open the hover-card.

Inbound Events

• hover-card:set - force open state

root.dispatchEvent(new CustomEvent("hover-card:set", { detail: { open: true } }));

Deprecated shape is still supported:

root.dispatchEvent(new CustomEvent("hover-card:set", { detail: { value: true } }));

Styling

Position is computed in JavaScript and applied as position: absolute + transform: translate3d(...). By default, content is portaled to document.body while open. The positioned element (hover-card-positioner, or hover-card-content when portal is disabled) receives --transform-origin, so animations can scale from the trigger anchor. Use data-open / data-closed, data-side, and data-align for animation/styling. Placement uses layout dimensions, so scale/zoom animations on hover-card-content stay aligned without requiring an extra inner wrapper.

[data-slot="hover-card-content"] {
  transform-origin: var(--transform-origin, center);
  --hover-card-slide-x: 0px;
  --hover-card-slide-y: -4px;
}

[data-slot="hover-card-content"][data-side="top"] {
  --hover-card-slide-y: 4px;
}
[data-slot="hover-card-content"][data-side="bottom"] {
  --hover-card-slide-y: -4px;
}
[data-slot="hover-card-content"][data-side="left"] {
  --hover-card-slide-x: 4px;
  --hover-card-slide-y: 0px;
}
[data-slot="hover-card-content"][data-side="right"] {
  --hover-card-slide-x: -4px;
  --hover-card-slide-y: 0px;
}

[data-slot="hover-card-content"][data-open] {
  animation: hover-card-in 160ms cubic-bezier(0.16, 1, 0.3, 1);
}

[data-slot="hover-card-content"][data-closed] {
  pointer-events: none;
  animation: hover-card-out 120ms ease-in forwards;
}

[data-slot="hover-card-content"][data-instant] {
  transition: none;
  animation: none;
}

Accessibility

The component automatically handles:

• aria-haspopup="dialog" on trigger
• aria-controls linking trigger to content
• aria-expanded state on trigger
• Unique content IDs via ensureId

Behavior

Warm-up Behavior

When one hover-card closes, another hovered shortly after can open immediately (delay skipped).

• Controlled by skipDelayDuration / data-skip-delay-duration
• Set to 0 to disable warm-up behavior
• Warm-up applies across hover-card instances
• Warm-up opens add data-instant (root/content/positioner) for that open cycle, so CSS can disable animations
• During warm handoff to another hover-card trigger, the stale popup closes immediately (bypasses closeDelay) and that close cycle is marked with data-instant