Hover Card
newSneak peek, no commitment. A preview card for links, shown on hover or focus.
Installation
Usage
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { HoverCard, HoverCardContent, HoverCardTrigger } from '@/components/ui/hover-card'
</script>
<template>
<HoverCard>
<HoverCardTrigger as-child>
<Button variant="link">@kappa-ui</Button>
</HoverCardTrigger>
<HoverCardContent>A preview of what the link leads to.</HoverCardContent>
</HoverCard>
</template>
On desktop, it opens when the pointer rests on the trigger or the trigger gets keyboard focus, and closes shortly after both are left.
It's for previews people can skip. Screen readers don't announce it, so keep anything important out of it.
On touch:
- Links open the card on a long press, and a tap still follows the link.
- Buttons and other elements open it on a tap and close it on the next one.
Once open, it stays while you scroll and closes on a tap outside or Escape. Want a long press everywhere? Set touch="long-press". No touch at all? Use touch="off".
update:open tells you why it opened or closed: trigger-hover, trigger-focus, trigger-press, outside-press, escape-key, scroll or disabled.
Examples
Delays
openDelay and closeDelay set how long to wait, in milliseconds, before the card opens and closes: 700 and 300 by default.
API Reference
HoverCardContent takes a class that merges with its own.
HoverCard
| Prop | Default | Type and description |
|---|---|---|
| open | — | booleanWhether it is open, bound with |
| defaultOpen | — | booleanWhether it starts open when |
| openDelay | — | numberMilliseconds the pointer rests on the trigger before the card opens. 700 by default. Touch opens at once, or after |
| closeDelay | — | numberMilliseconds the card stays after the pointer has left the trigger and the card, or focus has left the trigger. 300 by default. |
| restThreshold | — | numberSquared pointer movement, in pixels, below which the pointer counts as resting and the open delay keeps counting. 2 by default. |
| touch | — | TouchPolicyHow touch opens the card. |
| touchDelay | — | numberMilliseconds a finger holds the trigger before a long press opens the card. 500 by default. |
| disabled | — | booleanCloses the card and ignores the trigger while set. |
| Event | Payload and description |
|---|---|
| update:open | [open: boolean, details: HoverCardOpenChangeDetails]Fires when it opens or closes, with |
| Slot | Scope and description |
|---|---|
| default | { open: boolean; }The trigger and the content. Receives |
HoverCardTrigger
| Prop | Default | Type and description |
|---|---|---|
| reference | — | ReferenceElementA virtual element to position the card against instead of the trigger. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. A link by default. |
| Slot | Scope and description |
|---|---|
| default | {}The link the card belongs to, or a |
HoverCardContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the card mounted while closed, for animating it with a JavaScript library. |
| memoDependencies | — | unknown[]Values that should re-run the position update when they change. |
| side | — | "top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unless |
| sideOffset | 4 | numberDistance in pixels from the trigger. |
| sideFlip | — | booleanFlips to the opposite side when the preferred one would overflow. |
| align | — | "start" | "center" | "end"Alignment against the trigger along the chosen side. |
| alignOffset | — | numberOffset in pixels from the |
| alignFlip | — | booleanFlips the alignment when it would overflow. |
| avoidCollisions | — | booleanKeeps the card inside the collision boundary by flipping and shifting it. |
| collisionBoundary | — | Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default. |
| collisionPadding | — | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start. |
| arrowPadding | — | numberPadding between an arrow and the card's corners. |
| hideShiftedArrow | — | booleanHides an arrow when the card is shifted so far that the arrow would not point at the trigger. |
| sticky | — | "partial" | "always"
|
| hideWhenDetached | — | booleanHides the card when the trigger is scrolled out of view. |
| positionStrategy | — | "absolute" | "fixed"The CSS position used to place the card. |
| updatePositionStrategy | — | "always" | "optimized"
|
| disableUpdateOnLayoutShift | — | booleanStops recomputing the position when the layout shifts. |
| prioritizePosition | — | booleanKeeps the preferred side and alignment and lets the card overflow instead of flipping. |
| reference | — | ReferenceElementA virtual element to position against instead of the trigger. |
| dir | — | DirectionReading direction. Mirrors the layout and arrow keys in |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape while the card is open. |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside the card. Informational: the card decides on its own whether the press closes it. |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside the card. Informational: focus leaving never closes the card by itself. |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires for either of the two above. |
| Slot | Scope and description |
|---|---|
| default | {}The card's content. |
Props
- open
booleanWhether it is open, bound withv-model:open. A change from outside emits nothing.- defaultOpen
booleanWhether it starts open whenv-model:openis not used.- openDelay
numberMilliseconds the pointer rests on the trigger before the card opens. 700 by default. Touch opens at once, or aftertouchDelayon a long press.- closeDelay
numberMilliseconds the card stays after the pointer has left the trigger and the card, or focus has left the trigger. 300 by default.- restThreshold
numberSquared pointer movement, in pixels, below which the pointer counts as resting and the open delay keeps counting. 2 by default.- touch
TouchPolicyHow touch opens the card.auto(the default) long-presses a link or another element with a native long press and taps anything else;long-pressalways waits for the long press;offleaves touch alone. A touch-opened card stays until a tap outside, Escape ordisabled.- touchDelay
numberMilliseconds a finger holds the trigger before a long press opens the card. 500 by default.- disabled
booleanCloses the card and ignores the trigger while set.
Emits
- update:open
[open: boolean, details: HoverCardOpenChangeDetails]Fires when it opens or closes, with{ reason, event }:trigger-hover,trigger-focus,trigger-press,outside-press,escape-key,scrollordisabled.
Slots
- default
{ open: boolean; }The trigger and the content. Receivesopen.
Props
- reference
ReferenceElementA virtual element to position the card against instead of the trigger.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. A link by default.
Slots
- default
{}The link the card belongs to, or aButtonwithas-child.
Props
- forceMount
booleanKeeps the card mounted while closed, for animating it with a JavaScript library.- memoDependencies
unknown[]Values that should re-run the position update when they change.- side
"top" | "right" | "bottom" | "left"The side of the trigger to open on. Flips to the other side when there is no room, unlessavoidCollisionsis off.- sideOffset
4 numberDistance in pixels from the trigger.- sideFlip
booleanFlips to the opposite side when the preferred one would overflow.- align
"start" | "center" | "end"Alignment against the trigger along the chosen side.- alignOffset
numberOffset in pixels from thealignposition.- alignFlip
booleanFlips the alignment when it would overflow.- avoidCollisions
booleanKeeps the card inside the collision boundary by flipping and shifting it.- collisionBoundary
Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default.- collisionPadding
number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start.- arrowPadding
numberPadding between an arrow and the card's corners.- hideShiftedArrow
booleanHides an arrow when the card is shifted so far that the arrow would not point at the trigger.- sticky
"partial" | "always"partialkeeps the card attached to the trigger while scrolling;alwaysalso lets it detach from the trigger to stay in the boundary.- hideWhenDetached
booleanHides the card when the trigger is scrolled out of view.- positionStrategy
"absolute" | "fixed"The CSS position used to place the card.- updatePositionStrategy
"always" | "optimized"alwaysrecomputes the position on every animation frame instead of only on layout changes.- disableUpdateOnLayoutShift
booleanStops recomputing the position when the layout shifts.- prioritizePosition
booleanKeeps the preferred side and alignment and lets the card overflow instead of flipping.- reference
ReferenceElementA virtual element to position against instead of the trigger.- dir
DirectionReading direction. Mirrors the layout and arrow keys inrtl.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- escapeKeyDown
[event: KeyboardEvent]Fires on Escape while the card is open.preventDefault()keeps the card open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a pointer press outside the card. Informational: the card decides on its own whether the press closes it.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside the card. Informational: focus leaving never closes the card by itself.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires for either of the two above.
Slots
- default
{}The card's content.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| hover-card-trigger | data-state | The trigger, a link by default. |
| hover-card-content | data-state, data-side, data-align | The card. |