Hover Card
SaveA rich preview of a person, repository, or link that opens on hover and keyboard focus, built on Base UI Preview Card.
- Category
- Overlays
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Hover Card preview
Rate limits per plan were reviewed by Mira Okafor and merged into shaken/agent-runtime.
Installation
npx @shakenui/cli add hover-cardReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add hover-card --dry-runUsage
hover-card-example.tsx
import { HoverCard, HoverCardContent, HoverCardHeader, HoverCardMeta, HoverCardTrigger } from "@/components/shaken/ui/hover-card";
const icon = { "aria-hidden": true, viewBox: "0 0 16 16", fill: "none" } as const;
const stroke = { stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round" } as const;
export default function HoverCardExample() {
return (
<p className="max-w-md text-center text-sm leading-7 text-zinc-600 dark:text-zinc-400">
Rate limits per plan were reviewed by{" "}
<HoverCard>
<HoverCardTrigger href="#mira-okafor">Mira Okafor</HoverCardTrigger>
<HoverCardContent>
<HoverCardHeader>
<span
aria-hidden="true"
className="flex size-10 shrink-0 items-center justify-center rounded-full border border-zinc-950/10 text-sm font-medium text-zinc-700 dark:border-white/15 dark:text-zinc-300"
>
MO
</span>
<div className="grid min-w-0 gap-0.5">
<span className="font-semibold">Mira Okafor</span>
<span className="text-xs text-zinc-500">Staff engineer, Platform</span>
</div>
</HoverCardHeader>
<p className="mt-3 leading-relaxed text-zinc-600 dark:text-zinc-400">
Owns the API gateway and billing limits. Usually reviews within a few hours, Lagos time.
</p>
<HoverCardMeta>
<span className="inline-flex items-center gap-1.5">
<span aria-hidden="true" className="size-1.5 rounded-full bg-emerald-500" />
Available
</span>
<span className="font-mono tabular-nums">38 reviews this month</span>
</HoverCardMeta>
</HoverCardContent>
</HoverCard>{" "}
and merged into{" "}
<HoverCard>
<HoverCardTrigger href="#agent-runtime" className="font-mono text-[13px]">
shaken/agent-runtime
</HoverCardTrigger>
<HoverCardContent align="start">
<HoverCardHeader>
<span
aria-hidden="true"
className="flex size-10 shrink-0 items-center justify-center rounded-lg border border-zinc-950/10 text-zinc-600 dark:border-white/15 dark:text-zinc-400"
>
<svg {...icon} className="size-4">
<path d="M3.5 2.5h7.25a1.75 1.75 0 0 1 1.75 1.75v9.25H5.25A1.75 1.75 0 0 1 3.5 11.75v-9.25Z" {...stroke} />
<path d="M3.5 11.75A1.75 1.75 0 0 1 5.25 10h7.25" {...stroke} />
</svg>
</span>
<div className="grid min-w-0 gap-0.5">
<span className="truncate font-mono text-[13px] font-medium">shaken/agent-runtime</span>
<span className="text-xs text-zinc-500">Private repository</span>
</div>
</HoverCardHeader>
<p className="mt-3 leading-relaxed text-zinc-600 dark:text-zinc-400">
Runs agent plans step by step, with approvals, retries, and a replayable trace.
</p>
<HoverCardMeta>
<span>TypeScript</span>
<span className="inline-flex items-center gap-1 font-mono tabular-nums">
<svg {...icon}>
<path d="M8 2.25l1.7 3.6 3.8.5-2.8 2.65.7 3.85L8 11.05l-3.4 1.8.7-3.85L2.5 6.35l3.8-.5L8 2.25Z" {...stroke} />
</svg>
1,284
</span>
<span>Updated 2 hours ago</span>
</HoverCardMeta>
</HoverCardContent>
</HoverCard>
.
</p>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| HoverCard open / defaultOpen / onOpenChange | boolean / boolean / (open, details) => void | — | Root state. Leave open unset for an uncontrolled card. |
| HoverCardTrigger href | string | — | The link the card previews. It must still work for people who never see the card. |
| HoverCardTrigger delay / closeDelay | number | 600 / 300 | Milliseconds before opening and before closing. |
| HoverCardContent side / align | Side / "start" | "center" | "end" | "bottom" / "center" | Placement against the link. Flips when there is not enough room. |
| HoverCardContent sideOffset / alignOffset | number | 8 / 0 | Gap from the link and shift along its edge, in pixels. |
| HoverCardHeader / HoverCardMeta | ComponentProps<"div"> | — | Layout helpers: an avatar and name row, and a footer row of small facts under a divider. |
Accessibility
- The trigger is a real link (<a href>), so the destination is reachable without the card.
- The card opens on hover and on keyboard focus of the link, and closes on Escape, blur, or when the pointer leaves both the link and the card.
- The pointer can travel from the link into the card without it closing, so links inside the card can be clicked.
- The card is supplementary: nothing in it should be the only way to reach information or an action.
- It grows from the link in 160ms and fades out in 110ms; with reduced motion the transitions are removed.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/hover-card.tsxhover-card- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/hover-card/0.1.0.json.
ui/hover-card.tsxShowHide
ui/hover-card.tsx
"use client";
import { PreviewCard as BasePreviewCard } from "@base-ui/react/preview-card";
import type { ComponentProps } from "react";
type ClassName<State> = string | ((state: State) => string | undefined) | undefined;
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
/** Prepends base classes while keeping Base UI's state-function form of className working. */
function withBase<State>(base: string, className: ClassName<State>) {
return typeof className === "function" ? (state: State) => cx(base, className(state)) : cx(base, className);
}
/** Groups the hover card parts and holds its open state. Pass `open`/`onOpenChange` to control it. */
export const HoverCard = BasePreviewCard.Root;
/**
* The link that shows the card on hover and on keyboard focus. Renders an `<a>`, so give it an
* `href`: the card is a preview, and the link must still work for people who never see it.
* `delay` (default 600ms) and `closeDelay` (default 300ms) tune how eagerly it opens and closes.
*/
export function HoverCardTrigger({ className, ...props }: BasePreviewCard.Trigger.Props) {
return (
<BasePreviewCard.Trigger
className={withBase(
cx(
"rounded-sm font-medium text-zinc-950 underline decoration-zinc-950/25 underline-offset-[3px]",
"transition-[text-decoration-color] duration-150 ease-out motion-reduce:transition-none",
"hover:decoration-zinc-950/60 data-[popup-open]:decoration-zinc-950/60",
"dark:text-white dark:decoration-white/30 dark:hover:decoration-white/70 dark:data-[popup-open]:decoration-white/70",
"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
),
className,
)}
{...props}
/>
);
}
type PositionerProps = BasePreviewCard.Positioner.Props;
export interface HoverCardContentProps extends BasePreviewCard.Popup.Props {
/** Side of the trigger to place the card on. Flips when there is not enough room. */
side?: PositionerProps["side"];
/** Alignment against the trigger on the chosen side. */
align?: PositionerProps["align"];
/** Gap between the trigger and the card, in pixels. */
sideOffset?: PositionerProps["sideOffset"];
/** Shift along the trigger edge, in pixels. */
alignOffset?: PositionerProps["alignOffset"];
/** Classes for the positioner wrapper, for example to change the z-index. */
positionerClassName?: string;
/** Element to portal into. Defaults to `document.body`. */
container?: BasePreviewCard.Portal.Props["container"];
}
/**
* The floating card, rendered in a portal and positioned against the trigger. The pointer can
* travel from the link into the card without closing it, so links inside the card are reachable.
*/
export function HoverCardContent({
side = "bottom",
align = "center",
sideOffset = 8,
alignOffset = 0,
positionerClassName,
container,
className,
...props
}: HoverCardContentProps) {
return (
<BasePreviewCard.Portal container={container}>
<BasePreviewCard.Positioner
side={side}
align={align}
sideOffset={sideOffset}
alignOffset={alignOffset}
className={cx("z-50", positionerClassName)}
>
<BasePreviewCard.Popup
className={withBase(
cx(
"w-80 max-w-(--available-width) origin-(--transform-origin) rounded-xl p-4 text-sm",
"border border-zinc-950/10 bg-white text-zinc-950 shadow-[0_12px_32px_-8px_rgb(0_0_0/0.18)]",
"dark:border-white/15 dark:bg-black dark:text-white dark:shadow-[0_16px_48px_-12px_rgb(0_0_0/1),inset_0_1px_0_rgb(255_255_255/0.08)]",
"outline-none",
// Enter: 160ms from 96% at the trigger, plus a 4px drift toward its side. Exit: 110ms fade.
"transition-[opacity,scale,translate] duration-160 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none",
"data-[starting-style]:opacity-0 motion-safe:data-[starting-style]:scale-96",
"motion-safe:data-[side=bottom]:data-[starting-style]:-translate-y-1 motion-safe:data-[side=top]:data-[starting-style]:translate-y-1",
"motion-safe:data-[side=left]:data-[starting-style]:translate-x-1 motion-safe:data-[side=right]:data-[starting-style]:-translate-x-1",
"data-[ending-style]:opacity-0 data-[ending-style]:duration-110 data-[ending-style]:ease-out motion-safe:data-[ending-style]:scale-98",
),
className,
)}
{...props}
/>
</BasePreviewCard.Positioner>
</BasePreviewCard.Portal>
);
}
/** The top row of a card: an avatar or mark next to a name and a secondary line. */
export function HoverCardHeader({ className, ...props }: ComponentProps<"div">) {
return <div className={cx("flex items-start gap-3", className)} {...props} />;
}
/** A row of small facts at the bottom of a card, set off by a divider. */
export function HoverCardMeta({ className, ...props }: ComponentProps<"div">) {
return (
<div
className={cx(
"-mx-4 mt-4 -mb-4 flex flex-wrap items-center gap-x-4 gap-y-1 border-t border-zinc-950/[0.07] px-4 py-3 text-xs text-zinc-500",
"dark:border-white/[0.08] [&_svg]:size-3.5 [&_svg]:shrink-0",
className,
)}
{...props}
/>
);
}