# Hover Card
> Rich previews that open on hover or focus.
Category: Overlay. Docs: https://neonkit.heyaadi.com/components/hover-card
## Installation
```bash
npx shadcn@latest add https://neonkit.heyaadi.com/r/hover-card.json
```
With the `@neonkit` namespace configured: `npx shadcn@latest add @neonkit/hover-card`.
npm dependencies: `@floating-ui/react-dom`, `motion`. Also needs `lib/utils.ts` (`cn`) and `lib/neon.ts` (`neonVars`), which the CLI adds.
## Usage
```tsx
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card"
@mara
Mara Okafor · Design engineer, Lisbon
```
## Examples
### Profile preview
The card's border catches light from the side that faces the trigger.
```tsx
import { CalendarDays, GitPullRequest, MapPin } from "@/components/ui/icons";
import { Avatar } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card";
const people = {
mara: {
name: "Mara Okafor",
role: "Design engineer",
bio: "Builds the parts of Northlight you click on. Currently rebuilding the deploy timeline.",
place: "Lisbon",
joined: "Joined March 2021",
},
jonas: {
name: "Jonas Weber",
role: "Staff engineer, Edge",
bio: "Keeps cold starts under 50 ms. Will review your cache headers whether you ask or not.",
place: "Berlin",
joined: "Joined June 2019",
},
};
function Mention({ handle }: { handle: keyof typeof people }) {
const person = people[handle];
return (
@{handle}
{person.name}
@{handle} · {person.role}
{person.bio}
{person.place}
{person.joined}
);
}
export default function HoverCardDemo() {
return (
Pull request #482 · Merged
Warm the edge cache before promoting a deployment
Approved by and two hours ago.
);
}
```
### Link preview
side="top" and a shorter openDelay for inline links in running text.
```tsx
import { BookMarked, GitFork, Star } from "@/components/ui/icons";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card";
export default function HoverCardRepository() {
return (
The runtime is open source. Read the code at{" "}
northlight/edge-runtime
northlight/edge-runtime
A V8 isolate runtime for request handlers, with streaming responses and a 5 ms cold start.
TypeScript
4.8k
312
Updated 3 days ago
.
);
}
```
### Side and align
Cards to the right of a list, aligned to the top of each name. The light follows the side.
```tsx
import { Clock } from "@/components/ui/icons";
import { Avatar } from "@/components/ui/avatar";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/ui/hover-card";
const team = [
{ handle: "priya", name: "Priya Raman", role: "Product lead", city: "Bengaluru", time: "18:02", status: "online" },
{ handle: "jonas", name: "Jonas Weber", role: "Staff engineer", city: "Berlin", time: "14:32", status: "busy" },
{ handle: "ines", name: "Inês Duarte", role: "Brand designer", city: "Porto", time: "13:32", status: "away" },
{ handle: "sam", name: "Sam Whitaker", role: "Support", city: "Toronto", time: "08:32", status: "offline" },
] as const;
const statusLabel = { online: "Available", busy: "In a meeting", away: "Away", offline: "Offline" };
export default function HoverCardTeam() {
return (
{team.map((person) => (
{person.name}
{person.name}
{person.role} · {person.city}
{person.time} local time
{statusLabel[person.status]}
))}
);
}
```
## API reference
### HoverCard
Holds the open state and the timers. Renders no element of its own.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `openDelay` | `number` | `500` | Milliseconds the pointer rests on the trigger, or keyboard focus stays, before the card opens. |
| `closeDelay` | `number` | `200` | Milliseconds before closing after the pointer leaves, enough to cross onto the card. |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when hover, focus, Escape or an outside click changes the state. |
### HoverCardTrigger
Renders a link. Also accepts every native anchor attribute.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` | `false` | Merges hover behaviour onto its single child, e.g. your router's Link. |
### HoverCardContent
The card, portaled and positioned with floating-ui. Accepts native div attributes; it's w-72 with p-4 until you override them.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred side. Flips when there's no room. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along that side. |
| `sideOffset` | `number` | `8` | Gap from the trigger in px. |
| `color` | `NeonColor` | `inherited` | Palette name or hex. Without it the card takes the trigger's color, then --neon-accent, then cyan. |
## Accessibility
- Opens on mouse hover and on keyboard focus of the trigger. Touch is ignored, so a tap just follows the link.
- The card stays open while the pointer is over it, and while the trigger keeps keyboard focus.
- While open, the trigger's aria-describedby points at the card, so screen readers announce its text as a description.
- Escape closes it without moving focus.
- Content inside the card isn't in the tab order after the trigger. Keep anything essential reachable elsewhere, as you would for a tooltip.
## Source
`components/ui/hover-card.tsx`
```tsx
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import {
autoUpdate,
flip,
offset,
shift,
useFloating,
type Middleware,
type Placement,
} from "@floating-ui/react-dom";
import { cn } from "@/lib/utils";
import { neonVars, type NeonColor } from "@/lib/neon";
/** The single element in `node`. Server Components can pass it as a lazy reference, which Children resolves. */
function resolveElement
(child) ? child : null;
}
type RenderProp = { asChild?: boolean; render?: React.ReactElement; nativeButton?: boolean; children?: React.ReactNode };
/**
* Base UI spells asChild as `render={}` plus `nativeButton`, and the shadcn CLI rewrites
* asChild into that form in base-* projects. Folds it back into asChild and children.
*/
function fromRenderProp
({ render, nativeButton, ...props }: P): Omit {
void nativeButton; // Only meaningful to Base UI.
if (!render) return props;
const children = props.children === undefined ? render : React.cloneElement(render, undefined, props.children);
return { ...props, asChild: true, children };
}
type Side = "top" | "right" | "bottom" | "left";
type Align = "start" | "center" | "end";
type AnyProps = Record;
const EASE = [0.23, 1, 0.32, 1] as const;
const useIsomorphicLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
const subscribeNothing = () => () => {};
/** False on the server and during hydration, so the portal only renders in the browser. */
function useIsClient() {
return React.useSyncExternalStore(
subscribeNothing,
() => true,
() => false,
);
}
function getElementRef(element: React.ReactElement): React.Ref | undefined {
// React 19 moved `ref` into props and warns on `element.ref`; React 18 is the other way round.
const props = element.props as { ref?: React.Ref };
const legacy = element as unknown as { ref?: React.Ref };
const propGetter = Object.getOwnPropertyDescriptor(props, "ref")?.get as { isReactWarning?: boolean } | undefined;
if (propGetter?.isReactWarning) return legacy.ref;
const elementGetter = Object.getOwnPropertyDescriptor(element, "ref")?.get as { isReactWarning?: boolean } | undefined;
if (elementGetter?.isReactWarning) return props.ref;
return props.ref ?? legacy.ref;
}
function setRef(ref: React.Ref | undefined, value: T | null) {
if (typeof ref === "function") ref(value);
else if (ref) (ref as React.RefObject).current = value;
}
function useComposedRefs(a: React.Ref | undefined, b: React.Ref | undefined) {
return React.useCallback(
(node: T | null) => {
setRef(a, node);
setRef(b, node);
},
[a, b],
);
}
/** Our props first, the child's on top. Handlers run child first, then ours. */
function mergeProps(ours: AnyProps, theirs: AnyProps): AnyProps {
const merged: AnyProps = { ...ours, ...theirs };
for (const key of Object.keys(ours)) {
const a = ours[key];
const b = theirs[key];
if (/^on[A-Z]/.test(key) && typeof a === "function" && typeof b === "function") {
merged[key] = (...args: unknown[]) => {
(b as (...args: unknown[]) => void)(...args);
(a as (...args: unknown[]) => void)(...args);
};
} else if (key === "className") {
merged[key] = cn(a as string, b as string);
} else if (key === "style") {
merged[key] = { ...(a as object), ...(b as object) };
} else if (key === "aria-describedby" && a && b) {
merged[key] = `${b} ${a}`;
}
}
return merged;
}
const Slot = React.forwardRef>(
({ children, ...props }, forwardedRef) => {
const child = resolveElement(children as React.ReactNode);
const ref = useComposedRefs(forwardedRef, child ? getElementRef(child) : undefined);
if (!child) return null;
return React.cloneElement(child, { ...mergeProps(props, child.props), ref } as AnyProps);
},
);
Slot.displayName = "HoverCardSlot";
function isFocusVisible(element: Element) {
try {
return element.matches(":focus-visible");
} catch {
return true;
}
}
function readNeon(element: Element | null) {
if (!element || typeof window === "undefined") return undefined;
const styles = window.getComputedStyle(element);
return styles.getPropertyValue("--neon").trim() || styles.getPropertyValue("--neon-accent").trim() || undefined;
}
const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), Math.max(min, max));
// The point on the card's edge nearest the trigger: the light source for the border, and where it grows from.
const lightSource: Middleware = {
name: "lightSource",
fn({ x, y, rects, placement }) {
const side = placement.split("-")[0] as Side;
const { width, height } = rects.floating;
const alongX = clamp(rects.reference.x + rects.reference.width / 2 - x, 16, width - 16);
const alongY = clamp(rects.reference.y + rects.reference.height / 2 - y, 16, height - 16);
const [lx, ly] = {
top: [alongX, height],
bottom: [alongX, 0],
left: [width, alongY],
right: [0, alongY],
}[side];
return { data: { x: lx, y: ly } };
},
};
const nudges: Record = {
top: { y: 4 },
bottom: { y: -4 },
left: { x: 4 },
right: { x: -4 },
};
interface HoverCardContextValue {
id: string;
contentId: string;
open: boolean;
triggerEl: HTMLElement | null;
setTriggerEl: (element: HTMLElement | null) => void;
onTriggerEnter: () => void;
onTriggerLeave: () => void;
onTriggerFocus: () => void;
onTriggerBlur: () => void;
onContentEnter: () => void;
onContentLeave: () => void;
}
const HoverCardContext = React.createContext(null);
function useHoverCard(component: string) {
const context = React.useContext(HoverCardContext);
if (!context) throw new Error(`<${component}> must be rendered inside .`);
return context;
}
export interface HoverCardProps {
/** Milliseconds the pointer rests on the trigger before the card opens. */
openDelay?: number;
/** Milliseconds after the pointer leaves before the card closes; time to cross the gap onto it. */
closeDelay?: number;
open?: boolean;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
children?: React.ReactNode;
}
function HoverCard({
openDelay = 500,
closeDelay = 200,
open: openProp,
defaultOpen = false,
onOpenChange,
children,
}: HoverCardProps) {
const id = React.useId();
const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
const [triggerEl, setTriggerEl] = React.useState(null);
const isControlled = openProp !== undefined;
const open = isControlled ? openProp : uncontrolledOpen;
const openRef = React.useRef(open);
const timer = React.useRef(0);
// Where the card's attention is: a hovered trigger or card, or a keyboard-focused trigger.
const hovering = React.useRef(false);
const focused = React.useRef(false);
useIsomorphicLayoutEffect(() => {
openRef.current = open;
});
const setOpen = React.useCallback(
(next: boolean) => {
window.clearTimeout(timer.current);
if (next === openRef.current) return;
if (!isControlled) setUncontrolledOpen(next);
onOpenChange?.(next);
},
[isControlled, onOpenChange],
);
const scheduleOpen = React.useCallback(() => {
window.clearTimeout(timer.current);
if (openRef.current) return;
timer.current = window.setTimeout(() => setOpen(true), openDelay);
}, [openDelay, setOpen]);
const scheduleClose = React.useCallback(() => {
window.clearTimeout(timer.current);
if (hovering.current || focused.current) return;
timer.current = window.setTimeout(() => setOpen(false), closeDelay);
}, [closeDelay, setOpen]);
React.useEffect(() => () => window.clearTimeout(timer.current), []);
React.useEffect(() => {
if (!open) return;
const onKeyDown = (event: KeyboardEvent) => {
if (event.key !== "Escape") return;
// Close the card first, not the dialog or menu it sits in.
event.preventDefault();
setOpen(false);
};
const onPointerDown = (event: PointerEvent) => {
const target = event.target as Element | null;
if (target?.closest?.(`[data-neonkit-hover-card="${id}"]`) || (target && triggerEl?.contains(target))) return;
hovering.current = false;
focused.current = false;
setOpen(false);
};
document.addEventListener("keydown", onKeyDown);
document.addEventListener("pointerdown", onPointerDown, true);
return () => {
document.removeEventListener("keydown", onKeyDown);
document.removeEventListener("pointerdown", onPointerDown, true);
};
}, [open, id, triggerEl, setOpen]);
const value = React.useMemo(
() => ({
id,
contentId: `${id}-content`,
open,
triggerEl,
setTriggerEl,
onTriggerEnter: () => {
hovering.current = true;
scheduleOpen();
},
onTriggerLeave: () => {
hovering.current = false;
scheduleClose();
},
onTriggerFocus: () => {
focused.current = true;
scheduleOpen();
},
onTriggerBlur: () => {
focused.current = false;
scheduleClose();
},
onContentEnter: () => {
hovering.current = true;
window.clearTimeout(timer.current);
},
onContentLeave: () => {
hovering.current = false;
scheduleClose();
},
}),
[id, open, triggerEl, scheduleOpen, scheduleClose],
);
return {children};
}
HoverCard.displayName = "HoverCard";
export interface HoverCardTriggerProps extends React.AnchorHTMLAttributes {
/** Merge hover behaviour onto the single child element instead of rendering a link. */
asChild?: boolean;
/** Base UI-style asChild: `render={}`. */
render?: React.ReactElement;
/** Accepted for Base UI compatibility; no effect. */
nativeButton?: boolean;
}
const HoverCardTrigger = React.forwardRef(
(raw, forwardedRef) => {
const {
asChild = false,
className,
onPointerEnter,
onPointerLeave,
onFocus,
onBlur,
"aria-describedby": ariaDescribedBy,
...props
} = fromRenderProp(raw);
const card = useHoverCard("HoverCardTrigger");
const ref = useComposedRefs(forwardedRef, card.setTriggerEl);
const describedBy = [ariaDescribedBy, card.open ? card.contentId : undefined].filter(Boolean).join(" ") || undefined;
const triggerProps = {
...props,
"data-state": card.open ? "open" : "closed",
onPointerEnter: (event: React.PointerEvent) => {
onPointerEnter?.(event);
// Touch has no hover; a tap should just follow the link.
if (!event.defaultPrevented && event.pointerType === "mouse") card.onTriggerEnter();
},
onPointerLeave: (event: React.PointerEvent) => {
onPointerLeave?.(event);
if (event.pointerType === "mouse") card.onTriggerLeave();
},
onFocus: (event: React.FocusEvent) => {
onFocus?.(event);
if (!event.defaultPrevented && isFocusVisible(event.currentTarget)) card.onTriggerFocus();
},
onBlur: (event: React.FocusEvent) => {
onBlur?.(event);
card.onTriggerBlur();
},
};
if (asChild) {
return (
}
className={className}
aria-describedby={describedBy}
{...(triggerProps as React.HTMLAttributes)}
/>
);
}
return (
);
},
);
HoverCardTrigger.displayName = "HoverCardTrigger";
export interface HoverCardContentProps
extends Omit<
React.HTMLAttributes,
"color" | "onAnimationStart" | "onAnimationEnd" | "onAnimationIteration" | "onDrag" | "onDragStart" | "onDragEnd"
> {
side?: Side;
align?: Align;
/** Gap between the trigger and the card, in px. */
sideOffset?: number;
/** Palette name or hex. When omitted the card takes the trigger's color, then `--neon-accent`. */
color?: NeonColor;
}
const HoverCardSurface = React.forwardRef(
(
{ side, align, sideOffset = 8, color, className, style, children, onPointerEnter, onPointerLeave, ...props },
ref,
) => {
const card = useHoverCard("HoverCardContent");
const reduceMotion = useReducedMotion() ?? false;
const [floatingEl, setFloatingEl] = React.useState(null);
const placement = (align === "center" ? side : `${side}-${align}`) as Placement;
const { floatingStyles, middlewareData, placement: finalPlacement } = useFloating({
placement,
strategy: "fixed",
open: true,
elements: { reference: card.triggerEl, floating: floatingEl },
whileElementsMounted: autoUpdate,
middleware: [offset(sideOffset), flip({ padding: 8 }), shift({ padding: 8 }), lightSource],
});
const finalSide = finalPlacement.split("-")[0] as Side;
const light = middlewareData.lightSource as { x: number; y: number } | undefined;
const at = light ? `${light.x}px ${light.y}px` : "50% 0%";
// A portal leaves the trigger's subtree, so carry its color over.
const inherited = React.useMemo(() => (color ? undefined : readNeon(card.triggerEl)), [color, card.triggerEl]);
const colorStyle = color
? neonVars(color)
: inherited
? ({ "--neon": inherited, "--neon-accent": inherited } as React.CSSProperties)
: undefined;
// Only the 1px border ring shows the light: the padding box is masked out.
const ring = "linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0)";
return (
{
onPointerEnter?.(event);
if (event.pointerType === "mouse") card.onContentEnter();
}}
onPointerLeave={(event) => {
onPointerLeave?.(event);
if (event.pointerType === "mouse") card.onContentLeave();
}}
{...props}
>