Hover Card
The React Hover Card component shows a small preview panel when a user hovers over an element. It is used to display extra information without leaving the page.
It helps users quickly view details without having to click. For example, you can display a user profile, product info, or a link preview when hovering over a name or an item.
Built with Base UI's PreviewCard component and styled using Tailwind CSS. It supports positioning, delays, keyboard access, and accessible interactions.
Installation
Install the component using the Tailgrids CLI.
npx @tailgrids/cli add hover-cardAnatomy
Import the sub-components and compose them.
import {
HoverCard,
HoverCardTrigger,
HoverCardContent
} from "@/registry/core/hover-card";
export const HoverCardAnatomy = () => (
<HoverCard>
<HoverCardTrigger>Hover me</HoverCardTrigger>
<HoverCardContent>The content to display on hover.</HoverCardContent>
</HoverCard>
);Examples
Profile Preview
A common use case for hover cards is displaying user profile metadata when hovering over a username or avatar.
Product Preview
Hover cards can also be used to show a quick summary of a product, including an image, price, and description.
Placement
Use the side and align props to control the position of the hover card relative to its trigger.
Custom Animation
You can customize the entrance and exit animations of the hover card using CSS transitions or animations, often by targeting the data-state attribute or using framer-motion.
API Reference
HoverCard
The root component that manages the state and coordination of the hover card.
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | - | Whether the hover card is currently open. |
onOpenChange | (open: boolean) => void | - | Event handler called when the hover card is opened or closed. |
defaultOpen | boolean | false | Whether the hover card is initially open. |
actionsRef | Ref<Actions> | - | A ref to imperative actions (e.g., close, unmount). |
HoverCardTrigger
The element that opens the hover card on hover.
| Prop | Type | Default | Description |
|---|---|---|---|
href | string | - | The URL that the hyperlink points to. |
delay | number | 600 | How long to wait before the hover card opens (ms). |
closeDelay | number | 300 | How long to wait before the hover card closes (ms). |
payload | any | - | A payload to pass to the hover card when it is opened. |
render | ReactElement | function | - | Allows replacing the HTML element or composing with another component. |
HoverCardContent
The container for the hover card contents, which includes positioning logic.
| Prop | Type | Default | Description |
|---|---|---|---|
side | 'top' | 'bottom' | 'left' | 'right' | 'bottom' | Which side of the trigger to align against. |
sideOffset | number | 4 | Distance between the anchor and the popup (px). |
align | 'start' | 'center' | 'end' | 'center' | How to align the popup relative to the side. |
alignOffset | number | 4 | Additional offset along the alignment axis (px). |
className | string | - | Additional CSS classes for the content container. |
See Base UI documentation for more information.
Accessibility
- Keyboard support: The trigger element can receive focus, allowing keyboard users to access the hover card.
- Focus behavior: When the trigger is focused, the hover card can open just like on hover.
- Screen reader support: Use clear text or labels on the trigger so screen readers can describe what the hover card represents.
- Positioning and timing: You can control open and close delays to make the interaction more usable and predictable.
- Controlled state: You can control the open state manually to manage visibility in more complex or accessibility-focused use cases.
