---
title: Hover Card
description: Preview content behind a link on hover or keyboard focus.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Hover Card

> Preview content behind a link on hover or keyboard focus.

## Anatomy

```text
HoverCard [component; no DOM]
├── HoverCard.Trigger [part; slot=trigger]
└── positioner [internal]
    └── HoverCard.Content [part; slot=content]
```

Content is portaled inside an internal positioning wrapper.

## Usage

Use HoverCard to preview the destination of a link on hover or keyboard focus. The trigger
defaults to an anchor element, so compose it directly inside prose. Use
[Tooltip](https://moraine.subf.dev/components/tooltip.md) for a brief, non-interactive hint and
[Popover](https://moraine.subf.dev/components/popover.md) for content the user must reach and operate.

```tsx
import { HoverCard } from 'moraine'

export function Example() {
  return (
    <HoverCard>
      <HoverCard.Trigger href="/u/alex.morgan">@alex.morgan</HoverCard.Trigger>
      <HoverCard.Content>Author profile preview</HoverCard.Content>
    </HoverCard>
  )
}
```

### Delays and anchoring

`openDelay` (default 600 ms) keeps the card from opening on a passing pointer, and `closeDelay`
(default 300 ms) keeps it open while the pointer travels from the trigger into the content. The
card anchors to the line the pointer entered, so it stays attached when the trigger wraps across
multiple lines. `placement` defaults to `'bottom'`, and `gutter` defaults to 4 px.

```tsx
<HoverCard openDelay={200} closeDelay={100} placement="top" align="start">
  <HoverCard.Trigger href="/releases/v2">v2 release notes</HoverCard.Trigger>
  <HoverCard.Content>Ships December 15.</HoverCard.Content>
</HoverCard>
```

### Dismissal and accessibility

Escape and a pointer press outside close the card; hover or keyboard focus reopens it. Control the
open state with `open` and `onOpenChange`, or start open with `defaultOpen`. `disabled` keeps the
card closed. `forceMount` keeps the content in the DOM while closed.

Hover card content is supplementary: keyboard users cannot reach it and screen readers do not
announce it, so it must never be the only place the information lives. Make the same content
available at the link destination.

```tsx
<HoverCard>
  <HoverCard.Trigger href="/u/alex.morgan">@alex.morgan</HoverCard.Trigger>
  <HoverCard.Content>Profile summary also shown on the author page.</HoverCard.Content>
</HoverCard>
```

### Keyboard interaction

Moving keyboard focus to the trigger opens the card after `openDelay`, and blurring the trigger
closes it after `closeDelay`. Only keyboard (focus-visible) focus opens the card, and touch hover
is ignored. The card itself is not keyboard reachable; keep interactive content in a
[Popover](https://moraine.subf.dev/components/popover.md) instead.

## Examples

### Preview a profile inside prose

Hover or focus the link to preview the author. The trigger wraps across lines like any
inline anchor, and the card anchors to the line the pointer entered.

```tsx
import { Avatar, Badge, HoverCard } from 'moraine'

export function ProfilePreview() {
  return (
    <p class="text-sm text-foreground leading-6 max-w-xs">
      The component library is maintained by{' '}
      <HoverCard openDelay={200} closeDelay={120}>
        <HoverCard.Trigger href="/u/alex.morgan" class="font-medium underline underline-offset-4">
          @alex.morgan
        </HoverCard.Trigger>
        <HoverCard.Content>
          <div class="space-y-3">
            <Avatar text="AM" alt="Alex Morgan" size="lg" />
            <div>
              <div class="flex gap-1.5 items-center">
                <h4 class="text-sm font-semibold">Alex Morgan</h4>
                <Badge variant="outline" size="sm">
                  Maintainer
                </Badge>
              </div>
              <p class="text-xs text-muted-foreground font-mono">@alex.morgan</p>
            </div>
            <p class="text-xs text-foreground">
              Building accessible, high-performance UI primitives for SolidJS and web standards.
            </p>
            <div class="text-xs text-muted-foreground pt-2 border-t border-border flex gap-3">
              <span>
                <strong class="text-foreground font-semibold">1.4k</strong> followers
              </span>
              <span>
                <strong class="text-foreground font-semibold">328</strong> following
              </span>
            </div>
          </div>
        </HoverCard.Content>
      </HoverCard>{' '}
      and the wider community, with new primitives landing in each release cycle.
    </p>
  )
}
```

### Share one card across multiple triggers

Mount one hover card instead of one per link. Put a `value` on each `Trigger` under one root and
read it from the function children of `HoverCard.Content`: hovering another trigger moves the same
card to it.

```tsx
import { Avatar, HoverCard, Icon } from 'moraine'

const profiles = {
  ananya: {
    name: 'Ananya Rao',
    bio: 'Maintains the overlay primitives and the positioning layer.',
    joined: 'Joined March 2022',
  },
  jules: {
    name: 'Jules Ferreira',
    bio: 'Works on recipes, tokens, and theme compilation.',
    joined: 'Joined June 2022',
  },
  nico: {
    name: 'Nico Tanaka',
    bio: 'Keeps the docs site and the component examples current.',
    joined: 'Joined January 2023',
  },
} as const

export function MultipleTriggers() {
  return (
    <HoverCard openDelay={300}>
      <p class="text-sm text-foreground leading-6 max-w-xs">
        This release was reviewed by{' '}
        <HoverCard.Trigger value="ananya" href="/u/ananya" class="font-medium">
          @ananya
        </HoverCard.Trigger>
        {', '}
        <HoverCard.Trigger value="jules" href="/u/jules" class="font-medium">
          @jules
        </HoverCard.Trigger>
        {', and '}
        <HoverCard.Trigger value="nico" href="/u/nico" class="font-medium">
          @nico
        </HoverCard.Trigger>
        .
      </p>
      <HoverCard.Content>
        {(context) => {
          const profile = () => profiles[(context.value() ?? 'ananya') as keyof typeof profiles]
          return (
            <div class="flex gap-4">
              <Avatar text={profile().name.slice(0, 2).toUpperCase()} alt={profile().name} />
              <div class="space-y-1">
                <h4 class="text-sm font-semibold">{profile().name}</h4>
                <p class="text-sm">{profile().bio}</p>
                <div class="pt-2 flex gap-2 items-center">
                  <Icon name="i-lucide:calendar-days" class="opacity-70 size-4" />
                  <span class="text-xs text-muted-foreground">{profile().joined}</span>
                </div>
              </div>
            </div>
          )
        }}
      </HoverCard.Content>
    </HoverCard>
  )
}
```

### Preview a link destination

Give a documentation link a small preview with the page title, a description, and the
resolved URL. The link wraps across several lines, and the card anchors to the line the
pointer entered.

```tsx
import { HoverCard, Icon } from 'moraine'

export function LinkPreview() {
  return (
    <p class="text-sm text-foreground leading-6 max-w-xs">
      New here? Start with the{' '}
      <HoverCard placement="top" openDelay={300}>
        <HoverCard.Trigger
          href="/docs/getting-started"
          class="font-medium underline underline-offset-4"
        >
          getting started guide for new contributors to the design system
        </HoverCard.Trigger>
        <HoverCard.Content>
          <div class="space-y-2">
            <h4 class="text-sm font-semibold">Getting started</h4>
            <p class="text-xs text-foreground">
              Install the library, register the preset, and render your first component in a few
              minutes.
            </p>
            <div class="text-xs text-muted-foreground pt-1 flex gap-2 items-center">
              <Icon name="i-lucide:link" class="size-3.5" />
              <span>moraine.dev/docs/getting-started</span>
            </div>
          </div>
        </HoverCard.Content>
      </HoverCard>{' '}
      before diving into individual primitives.
    </p>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-closed` | `hover-card-trigger`, `hover-card-content` | Present when disclosure or transition content is closed. |
| `data-disabled` | `hover-card-trigger` | Present when the component, slot, or item is disabled. |
| `data-expanded` | `hover-card-trigger`, `hover-card-content` | Present when the panel, accordion, or menu is expanded. |
| `data-align` | `hover-card-content` | Stores the resolved alignment of positioned content. |
| `data-instant-motion` | `hover-card-content` | Present when enter and exit motion should complete immediately. |
| `data-side` | `hover-card-content` | Stores the resolved floating or drawer content side. |

### Props

#### HoverCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'start' \| 'center' \| 'end' \| undefined | 'center' | Alignment of the content along the trigger edge: `'start'` and `'end'` line up the content<br>edge with the matching trigger edge, `'center'` centers it. Combines with `placement`. |
| closeDelay | number \| undefined | 300 | Delay in milliseconds between the pointer leaving the trigger and content, or the trigger<br>losing focus, and closing. Moving onto the content within the delay keeps the card open. |
| defaultOpen | boolean \| undefined | false | Initial open state when uncontrolled. Ignored while `open` is set. |
| disabled | boolean \| undefined | false | Whether trigger interactions and content rendering are disabled. |
| flip | boolean \| string \| undefined | true | Whether the content moves to another side when the preferred `placement` does not fit in the<br>viewport. `false` keeps the side fixed. A string is a space-delimited list of fallback<br>placements tried in order, each `top`, `right`, `bottom` or `left`, optionally suffixed with<br>`-start` or `-end`; any other entry throws an error. |
| forceMount | boolean \| undefined | false | Whether the content stays in the DOM while closed, hidden and marked with `data-closed`, for<br>example to measure it or keep its state. Has no effect while `disabled`. |
| gutter | number \| undefined | 4 | Gap in pixels between the trigger and the content. |
| id | string \| undefined | — | Unique identifier used to derive the content id, which becomes `<id>-content`. Generated when<br>omitted. |
| onOpenChange | ((open: boolean) => void) \| undefined | — | Called with the next open state when an interaction (trigger press, hover or focus delay,<br>Escape, outside press) requests a change. It is not called when `open` is changed from outside,<br>and it does not apply the change itself when `open` is controlled: update `open` in the handler. |
| open | boolean \| undefined | — | Controlled open state. Pair it with `onOpenChange`; leave it `undefined` to let the component<br>manage its own state (see `defaultOpen`). `disabled` forces the content closed regardless. |
| openDelay | number \| undefined | 600 | Delay in milliseconds between a mouse pointer entering the trigger and opening. Keyboard<br>focus on the trigger also opens it after this delay, but only for focus-visible (keyboard)<br>focus. Touch hover is ignored. |
| overflowPadding | number \| undefined | 4 | Minimum padding in pixels between the content and the viewport edge. |
| placement | 'top' \| 'right' \| 'bottom' \| 'left' \| undefined | 'bottom' | Side of the trigger the content opens on. The rendered side can differ when `flip` moves it to<br>fit the viewport; read it from `data-side` on the content. |
| shift | number \| undefined | 0 | Offset in pixels along the trigger edge (horizontal for `top` and `bottom` placements,<br>vertical for `left` and `right`), added to the position given by `align`. |
| slide | boolean \| undefined | true | Whether the content slides along the trigger edge (horizontally for `top` and `bottom`<br>placements, vertically for `left` and `right`) to stay inside the viewport, keeping<br>`overflowPadding` from the edge, instead of overflowing. |
| children | JSX.Element \| undefined | — | Composed trigger and content primitives. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`flip` example**

```tsx
import { Button, Popover } from 'moraine'

<Popover placement="bottom" flip="top bottom-end">
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>More information</Popover.Content>
</Popover>
```

**`onOpenChange` example**

```tsx
import { Button, Popover } from 'moraine'
import { createSignal } from 'solid-js'

const [open, setOpen] = createSignal(false)

<Popover open={open()} onOpenChange={setOpen}>
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>More information</Popover.Content>
</Popover>
```

#### HoverCard.Trigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | boolean \| undefined | — | Whether this trigger is disabled. |
| value | string \| undefined | — | Identifies this trigger when several triggers share one card. `HoverCard.Content` receives<br>the `value` of the trigger that most recently anchored the card through its function<br>children. |
| as | T \| undefined | 'a' | Element or component to render as. |
| children | JSX.Element \| undefined | — | Trigger label and visual content. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

#### HoverCard.Content

Props for the HoverCard component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | JSX.Element \| ((context: ContentContext) => JSX.Element) \| undefined | — | Card content shown while the card is open. A function receives `{ value }`, an accessor for<br>the `value` of the `HoverCard.Trigger` that anchored the card (`undefined` when that trigger<br>has no `value`). |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

**`children` example**

```tsx
import { HoverCard } from 'moraine'

<HoverCard>
  <HoverCard.Trigger href="/u/alex" value="alex">@alex</HoverCard.Trigger>
  <HoverCard.Trigger href="/u/sam" value="sam">@sam</HoverCard.Trigger>
  <HoverCard.Content>{({ value }) => <span>Profile of {value()}</span>}</HoverCard.Content>
</HoverCard>
```
