HoverCard

HoverCard is a floating content container that appears when a user hovers over or focuses on a trigger element. It is useful for previews, tooltips with rich content, user cards, and contextual details.

---

Usage

Basic usage

import { HoverCard } from '@nofinite/nui';

<HoverCard trigger={<span>Hover me</span>}>
  <div>This is a HoverCard.</div>
</HoverCard>;

With interactive trigger

import { HoverCard, Button } from '@nofinite/nui';

<HoverCard trigger={<Button>Details</Button>}>More details here...</HoverCard>;

---

Variants

HoverCard does not ship with predefined visual variants, but you can customize appearance using className.

<HoverCard trigger={<span>Hover me</span>} className="card-dark">
  Dark styled hover card
</HoverCard>

Guidelines:

• Use className for theme-based or contextual styling.
• Avoid excessive visual complexity inside the card to maintain hover usability.

---

Sizes

There are no built-in size props. Size is controlled by the content inside the card.

<HoverCard trigger={<span>Profile</span>}>
  <div style={{ width: 180 }}>Custom width HoverCard</div>
</HoverCard>

---

States

The HoverCard manages its own internal open/close state.

Supported interaction states:

• Hover / Focus – Opens after openDelay.
• Mouse leave / Blur – Closes after closeDelay.
• ESC key – Immediately closes the card.
• Outside click – Dismisses the card.
• Reduced motion – Animations are disabled if prefers-reduced-motion is enabled.

---

Native Props / Composition

The trigger and content are fully composable using React nodes.

<HoverCard trigger={<img src="/avatar.jpg" width={40} height={40} />}>
  <div>
    <strong>Samrat</strong>
    <p>Founder — XTech</p>
  </div>
</HoverCard>

For styling:

<HoverCard trigger={<span>Hover</span>} className="my-custom-hovercard">
  Custom styled content
</HoverCard>

---

Props

Prop	Type	Default	Description
trigger	ReactNode	—	Element that activates the HoverCard
children	ReactNode	—	Content rendered inside the HoverCard
openDelay	number	120	Delay (ms) before opening on hover/focus
closeDelay	number	140	Delay (ms) before closing on leave/blur
className	string	""	Additional class names for the card container

---

Behavior Notes

• The HoverCard opens on hover and keyboard focus.
• Position is calculated relative to the trigger and updated on scroll/resize.
• Rendered using a Portal, so it escapes overflow/stacking issues.
• Uses position: fixed for stable viewport positioning.
• Automatically stays open when hovering over the card itself.

Example:

<HoverCard trigger={<span>Hover</span>} openDelay={200} closeDelay={200}>
  Delayed HoverCard
</HoverCard>

---

Accessibility

• Renders as a <div role="dialog">.
• Opens on keyboard focus and closes on blur.
• ESC key closes the HoverCard.
• aria-hidden is applied when closed.
• Ensure the trigger element itself is keyboard-focusable.

Example:

<HoverCard trigger={<button aria-describedby="info">Info</button>}>
  Accessible hover content
</HoverCard>

---

Layout

• The trigger is rendered inline by default.
• The HoverCard is positioned absolutely via position: fixed.
• Width and layout are controlled by its children.
• Works well inside inline text, buttons, or icons.

<HoverCard trigger={<span style={{ display: 'inline-block' }}>Hover</span>}>
  <div style={{ width: '100%' }}>Full-width content</div>
</HoverCard>

---

Best Practices

Do

• Use for supplementary or preview information.
• Keep content concise and readable.
• Ensure triggers are accessible via keyboard.
• Add slight delays to avoid accidental flicker.

Don’t

• Use for critical actions or required content.
• Overload with large forms or complex interactions.
• Nest HoverCards inside other hover-driven components.
• Rely on hover-only behavior for essential information.