Hover Card

For sighted users to preview content available behind a link.

1
---
2
import { Button } from '@bejamas/ui/components/button';
3
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@bejamas/ui/components/hover-card';
4
---
5

6
<HoverCard delay={10} closeDelay={100}>
7
  <HoverCardTrigger asChild>
8
    <Button variant="link">@data-slot</Button>
9
  </HoverCardTrigger>
10
  <HoverCardContent class="flex w-64 flex-col gap-0.5">
11
    <div class="font-semibold">@data-slot</div>
12
    <div>Headless UI components for vanilla JavaScript.</div>
13
    <div class="text-muted-foreground mt-1 text-xs">
14
      Created by Bejamas in 2026
15
    </div>
16
  </HoverCardContent>
17
</HoverCard>

Installation

bunx bejamas add hover-card

npx bejamas add hover-card

pnpm dlx bejamas add hover-card

yarn dlx bejamas add hover-card

Usage

1
---
2
import {
3
  HoverCard,
4
  HoverCardContent,
5
  HoverCardTrigger,
6
} from '@bejamas/ui/components/hover-card';
7
import { Button } from '@bejamas/ui/components/button';
8
---
9

10
<HoverCard>
11
  <HoverCardTrigger asChild>
12
    <Button variant="link">Hover Here</Button>
13
  </HoverCardTrigger>
14
  <HoverCardContent>
15
    <div class="font-semibold">@nextjs</div>
16
    <div>The React Framework - created and maintained by @vercel.</div>
17
  </HoverCardContent>
18
</HoverCard>

Examples

With Avatar

1
---
2
import { Avatar, AvatarFallback, AvatarImage } from '@bejamas/ui/components/avatar';
3
import { Button } from '@bejamas/ui/components/button';
4
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@bejamas/ui/components/hover-card';
5
---
6

7
<HoverCard>
8
  <HoverCardTrigger asChild>
9
    <Button variant="link">@thom</Button>
10
  </HoverCardTrigger>
11
  <HoverCardContent class="flex w-72 gap-3 p-3">
12
    <Avatar class="size-10 rounded-full">
13
      <AvatarImage>
14
        <img src="https://github.com/thomkrupa.png" alt="@thom" />
15
      </AvatarImage>
16
      <AvatarFallback>TK</AvatarFallback>
17
    </Avatar>
18
    <div class="space-y-1">
19
      <div class="text-sm font-semibold leading-none">@thom</div>
20
      <p class="text-muted-foreground text-sm">
21
        Building design systems and UI tooling.
22
      </p>
23
    </div>
24
  </HoverCardContent>
25
</HoverCard>

Different sides

1
---
2
import { Button } from '@bejamas/ui/components/button';
3
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@bejamas/ui/components/hover-card';
4
---
5

6
<div class="flex flex-wrap items-center gap-3 py-8">
7
  <HoverCard delay={10} closeDelay={80} skipDelayDuration={0}>
8
    <HoverCardTrigger asChild>
9
      <Button variant="outline">Left</Button>
10
    </HoverCardTrigger>
11
    <HoverCardContent side="left">Appears on left.</HoverCardContent>
12
  </HoverCard>
13
  <HoverCard delay={10} closeDelay={80} skipDelayDuration={0}>
14
    <HoverCardTrigger asChild>
15
      <Button variant="outline">Top</Button>
16
    </HoverCardTrigger>
17
    <HoverCardContent side="top">Appears on top.</HoverCardContent>
18
  </HoverCard>
19
  <HoverCard delay={10} closeDelay={80} skipDelayDuration={0}>
20
    <HoverCardTrigger asChild>
21
      <Button variant="outline">Bottom</Button>
22
    </HoverCardTrigger>
23
    <HoverCardContent side="bottom">Appears on bottom.</HoverCardContent>
24
  </HoverCard>
25
  <HoverCard delay={10} closeDelay={80} skipDelayDuration={0}>
26
    <HoverCardTrigger asChild>
27
      <Button variant="outline">Right</Button>
28
    </HoverCardTrigger>
29
    <HoverCardContent side="right">Appears on right.</HoverCardContent>
30
  </HoverCard>
31
</div>

Positioning options

Configure placement options on HoverCardContent:

1
---
2
import { Button } from '@bejamas/ui/components/button';
3
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@bejamas/ui/components/hover-card';
4
---
5

6
<HoverCard>
7
  <HoverCardTrigger asChild>
8
    <Button variant="outline">Custom positioning</Button>
9
  </HoverCardTrigger>
10
  <HoverCardContent
11
    side="top"
12
    sideOffset={8}
13
    align="start"
14
  >
15
    Uses content-level positioning options.
16
  </HoverCardContent>
17
</HoverCard>

Custom timing

1
---
2
import { Button } from '@bejamas/ui/components/button';
3
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@bejamas/ui/components/hover-card';
4
---
5

6
<HoverCard delay={600} closeDelay={200} skipDelayDuration={300}>
7
  <HoverCardTrigger asChild>
8
    <Button variant="outline">Hover with delay</Button>
9
  </HoverCardTrigger>
10
  <HoverCardContent>
11
    Opens after 600ms, closes after 200ms.
12
  </HoverCardContent>
13
</HoverCard>

API Reference

Events

The hover card emits custom events that you can listen to:

Event	Detail	Description
`hover-card:change`	`{ open: boolean, reason: string, trigger: HTMLElement, content: HTMLElement }`	Fired when visibility changes

Waiting for logs…

1
<HoverCard id="my-hover-card">
2
  <HoverCardTrigger asChild>
3
    <Button variant="outline">Hover me</Button>
4
  </HoverCardTrigger>
5
  <HoverCardContent>
6
    Hover card content
7
  </HoverCardContent>
8
</HoverCard>
9

10
<script>
11
  const hoverCard = document.getElementById('my-hover-card');
12

13
  hoverCard.addEventListener('hover-card:change', (e) => {
14
    console.log('Is open:', e.detail.open);
15
    console.log('Reason:', e.detail.reason);
16
  });
17
</script>

Programmatic Control

You can control the hover card programmatically by dispatching a hover-card:set event:

const hoverCard = document.getElementById('my-hover-card');

// Open the hover card
hoverCard.dispatchEvent(new CustomEvent('hover-card:set', {
  detail: { open: true }
}));

// Close the hover card
hoverCard.dispatchEvent(new CustomEvent('hover-card:set', {
  detail: { open: false }
}));

Data Attributes

The hover card sets these data attributes that you can use for styling or querying state:

Attribute	Element	Description
`data-state`	hover-card, hover-card-content	Current state (`open` or `closed`)
`data-open`	hover-card, hover-card-content	Present while open
`data-closed`	hover-card, hover-card-content	Present while closed
`data-side`	hover-card-content	Position relative to trigger (`top`, `right`, `bottom`, or `left`)
`data-align`	hover-card-content	Alignment (`start`, `center`, or `end`)
`data-side-offset`	hover-card-content	Distance from trigger in pixels (default `4`)
`data-align-offset`	hover-card-content	Alignment-axis offset in pixels (default `0`)