suaveplan/packages/ui/react/react-ui/src/components/hover-card/hover-card.md

HoverCard

(no submodules)

- hover-card.variants — `hoverCardContentVariants` is…

• hover-card.variants — hoverCardContentVariants is the cva configuration powering the <HoverCardContent> floating panel. It is split from…

• hover-card.variants — hoverCardContentVariants is…

• hover-card.variants — hoverCardContentVariants is the cva configuration powering the <HoverCardContent> floating panel. It is split from…

• hover-card.variants — hoverCardContentVariants is…

• hover-card.variants — hoverCardContentVariants is the cva configuration powering the <HoverCardContent> floating panel. It is split from…

• hover-card.variants — hoverCardContentVariants is…

• hover-card.variants — hoverCardContentVariants is the cva configuration powering the <HoverCardContent> floating panel. It is split from…

• hover-card.variants — hoverCardContentVariants is the cva configuration powering the <HoverCardContent> floating panel. It is split from…

Purpose

<HoverCard> and its sub-components (<HoverCardTrigger>, <HoverCardPortal>, <HoverCardContent>, <HoverCardArrow>) are the chassis hover-card primitives built on @radix-ui/react-hover-card. Use this for non-modal previews that open on hover or focus over the trigger and dismiss on hover-out or blur — link previews, user-mention bios, contextual mini-cards.

Distinct from <Popover>: HoverCard is hover-driven (mouse-only by spec; touch devices fall back to tap-to-open) with openDelay / closeDelay hysteresis. Distinct from <Tooltip>: HoverCard panels can hold rich content (multiple paragraphs, images, action links); Tooltip is a single short label.

Features

• Opens on hover or focus over the trigger; closes on hover-out or blur.
• openDelay / closeDelay numeric hysteresis (default 700/300 ms — Radix defaults).
• Side / align positional API (side: top/right/bottom/left; align: start/center/end).
• Self-portals via <HoverCardPortal>.
• Optional <HoverCardArrow> decoration.
• Theme-driven cva via useThemedVariants("HoverCardContent").
• All sub-components forward refs.
• motion-reduce:animate-none collapses the open/close animations under prefers-reduced-motion: reduce.

Usage: Basic Example

import {
    HoverCard,
    HoverCardContent,
    HoverCardTrigger,
} from "@suaveplan/react-ui";

export function MentionPreview() {
    return (
        <HoverCard>
            <HoverCardTrigger>@suaveplan</HoverCardTrigger>
            <HoverCardContent>
                Component library for the Suaveplan platform.
            </HoverCardContent>
        </HoverCard>
    );
}

Usage: Advanced Example

import {
    HoverCard,
    HoverCardArrow,
    HoverCardContent,
    HoverCardTrigger,
} from "@suaveplan/react-ui";

interface User {
    readonly handle: string;
    readonly displayName: string;
    readonly bio: string;
    readonly avatarUrl: string;
}

export function UserMention({ user }: { user: User }) {
    return (
        <HoverCard openDelay={400} closeDelay={200}>
            <HoverCardTrigger asChild>
                <a href={`/${user.handle}`}>@{user.handle}</a>
            </HoverCardTrigger>
            <HoverCardContent side="top" align="start" sideOffset={8}>
                <HoverCardArrow />
                <div className="flex gap-3">
                    <img
                        src={user.avatarUrl}
                        alt=""
                        className="h-10 w-10 rounded-full"
                    />
                    <div>
                        <h4 className="font-semibold">{user.displayName}</h4>
                        <p className="text-sm text-muted-foreground">
                            @{user.handle}
                        </p>
                        <p className="mt-1 text-sm">{user.bio}</p>
                    </div>
                </div>
            </HoverCardContent>
        </HoverCard>
    );
}

API Reference

<HoverCard>

Prop	Type	Default	Description
open	boolean	uncontrolled	Controlled open state.
defaultOpen	boolean	false	Initial open state.
onOpenChange	(open: boolean) => void	none	Fires on open/close transitions.
openDelay	number	700	Delay (ms) before opening on hover.
closeDelay	number	300	Delay (ms) before closing on hover-out.

<HoverCardContent>

Same positional props as <PopoverContent> (side, align, sideOffset, alignOffset, avoidCollisions, collisionPadding).

<HoverCardTrigger>, <HoverCardArrow>, <HoverCardPortal>

Direct re-exports of the Radix sub-components.

Implementation Notes

• The chassis NEVER assigns a numeric z-index — Radix portals handle stacking.
• HoverCard is hover-driven and therefore inappropriate for touch-only UI; consider <Popover> (click-driven) for tap-to-open ergonomics.
• <HoverCardContent> self-portals via <HoverCardPortal> so consumers do not need to compose the portal manually.
• align="center" and sideOffset={4} are chassis defaults (matching shadcn upstream).