Hover Card

Content Strategy

Keep hover card content concise and scannable. Include only preview-level information (avatar, name, short bio, key metadata). Avoid placing interactive controls inside hover cards - if the user needs to take action, use a Popover instead. The content should give enough context to decide whether to click through.

Timing & Delays

The default openDelay=700 prevents accidental triggers when the pointer sweeps across the page. The closeDelay=300 gives users time to move the pointer into the card content. Avoid reducing openDelay below 200ms or users will see unwanted flashes. Increase delays for dense lists with many triggers.

Responsive Behavior

Hover cards are a pointer-centric pattern and are not triggered on touch devices. Ensure the content behind the hover card is still accessible through the trigger link or an alternative navigation path. On smaller viewports, the card automatically repositions with avoidCollisions to stay within the viewport.

Color & Contrast

The hover card uses bg-popover with text-popover-foreground for consistent contrast across light and dark modes. The shadow and border ensure the card is visually distinct from the page surface. Avoid custom background colors that may break contrast ratios.

Pointer-Only Pattern

Hover cards are designed for sighted pointer users. They do not respond to keyboard focus or touch events by default. Any information shown exclusively in a hover card should also be reachable via the trigger link itself. For keyboard-accessible supplementary information, use Tooltip (which responds to focus).

Keyboard Navigation

• Tab — Moves focus to the trigger element (does not open the card)
• Enter — Activates the trigger (e.g., follows the link); does not open the card
• Esc — Closes the hover card if it is open

Screen Reader Support

• The trigger announces its accessible name (text content or aria-label)
• Hover card content is not announced to screen readers - it is supplementary information for sighted users
• Use asChild with a link or button to ensure proper role semantics
• Add role="region" and aria-label on content if it contains critical supplementary info

Motion & Reduced Motion

The hover card uses fade and zoom animations on open/close. These animations automatically respect the prefers-reduced-motion media query. When reduced motion is preferred, the card appears and disappears instantly without transitions.

ARIA Attributes

{/* Trigger with descriptive content */}
<HoverCard>
  <HoverCardTrigger asChild>
    <a href="/user/nextjs" className="underline">
      @nextjs
    </a>
  </HoverCardTrigger>
  <HoverCardContent>
    <p>Profile preview for @nextjs</p>
  </HoverCardContent>
</HoverCard>

{/* Using asChild to preserve semantic HTML */}
<HoverCard>
  <HoverCardTrigger asChild>
    <Button variant="link" aria-label="Preview Next.js profile">
      @nextjs
    </Button>
  </HoverCardTrigger>
  <HoverCardContent>
    <div role="region" aria-label="User profile preview">
      <h4 className="text-sm font-semibold">@nextjs</h4>
      <p className="text-sm">The React Framework</p>
    </div>
  </HoverCardContent>
</HoverCard>