How to build an accessible HoverCard in React

The trigger opens on both mouseenter and focus (and closes on mouseleave/blur) so keyboard users get the same preview, and the content is marked role="complementary" to signal it is supplementary rather than a required dialog; the open/close delays prevent accidental flicker.

When to use a HoverCard

• Showing a rich preview (avatar, summary, links) when a user hovers or focuses a trigger
• Supplementary, non-essential context the user can ignore without losing functionality
• Cases needing an open/close delay so brief mouse passes do not flicker the card

When not to use it

• Short plain-text hints — use Tooltip
• Content the user must interact with or that should trap focus — use Popover or Modal
• Touch-primary flows where there is no hover — prefer a tap-triggered Popover

Keyboard interactions

Role complementary, verified at WCAG 2.2-AA.

• Tab
• Escape

Common mistakes

Avoid: Putting required actions (buttons users must click) inside HoverCardContent

Prefer: Use a Popover triggered by click so the surface is reliably reachable

Hover surfaces are transient and unreachable by touch and many keyboard paths, so essential controls get lost

Example

<HoverCard>
  <HoverCardTrigger><a href="/users/ada">@ada</a></HoverCardTrigger>
  <HoverCardContent>
    <Avatar name="Ada Lovelace" />
    <p>Wrote the first program.</p>
  </HoverCardContent>
</HoverCard>

See the full HoverCard reference →