skills/docs/ui/react/react-ui/src/components/popover/popover.md

Popover

(no submodules)

- popover.variants — `popoverContentVariants` is the……

• popover.variants — popoverContentVariants is the cva configuration powering the <PopoverContent> floating panel. It is split from `pop…

• popover.variants — popoverContentVariants is the……

• popover.variants — popoverContentVariants is the cva configuration powering the <PopoverContent> floating panel. It is split from `pop…

• popover.variants — popoverContentVariants is the……

• popover.variants — popoverContentVariants is the cva configuration powering the <PopoverContent> floating panel. It is split from `pop…

• popover.variants — popoverContentVariants is the…

• popover.variants — popoverContentVariants is the cva configuration powering the <PopoverContent> floating panel. It is split from `pop…

• popover.variants — popoverContentVariants is the cva configuration powering the <PopoverContent> floating panel. It is split from `pop…

Purpose

<Popover> and its sub-components (<PopoverTrigger>, <PopoverAnchor>, <PopoverPortal>, <PopoverContent>, <PopoverArrow>, <PopoverClose>) are the chassis floating-panel primitives built on @radix-ui/react-popover. Use this for non-modal ephemeral content — info bubbles, compact pickers, link previews — where focus does NOT need to be trapped.

Distinct from <Dialog> and <AlertDialog>: a popover is non-modal so focus is not trapped, clicking outside dismisses it, and Escape dismisses it. There is no required title (popovers narrate their accessible name via their content). Radix handles the floating-UI math (avoid-collisions, sticky positioning, side/align resolution); the chassis adds the cva visual recipe.

Features

• Side / align positional API (side: top/right/bottom/left; align: start/center/end).
• sideOffset / alignOffset numeric offsets pass through to Radix.
• Self-portals via <PopoverPortal> so consumers do not need to compose the portal manually.
• Click-outside dismissal.
• Escape closes.
• Optional <PopoverArrow> decoration pointing back at the trigger.
• Optional <PopoverAnchor> lets the visual trigger differ from the popover anchor (e.g. anchor to a parent container).
• Theme-driven cva via useThemedVariants("PopoverContent").
• All sub-components forward refs.
• motion-reduce:animate-none collapses the open/close animations under prefers-reduced-motion: reduce.

Usage: Basic Example

import {
    Popover,
    PopoverContent,
    PopoverTrigger,
} from "@suaveplan/react-ui";

export function HelpBubble() {
    return (
        <Popover>
            <PopoverTrigger>Help</PopoverTrigger>
            <PopoverContent>
                Detailed help text for the focused control.
            </PopoverContent>
        </Popover>
    );
}

Usage: Advanced Example

import {
    Popover,
    PopoverArrow,
    PopoverAnchor,
    PopoverClose,
    PopoverContent,
    PopoverTrigger,
} from "@suaveplan/react-ui";
import { useState } from "react";

export function ColorPicker() {
    const [color, setColor] = useState("#3b82f6");
    return (
        <Popover>
            <PopoverTrigger
                aria-label="Pick a colour"
                style={{ background: color, width: 24, height: 24 }}
            />
            <PopoverContent side="bottom" align="start" sideOffset={8}>
                <PopoverArrow />
                <input
                    type="color"
                    value={color}
                    onChange={(e) => setColor(e.target.value)}
                />
                <PopoverClose>Done</PopoverClose>
            </PopoverContent>
        </Popover>
    );
}

API Reference

<Popover>

Wraps the Radix Popover Root. Same open / defaultOpen / onOpenChange lifecycle props as the other overlays.

<PopoverTrigger>

The visual trigger — a <button> by default; asChild polymorphic.

<PopoverContent>

Prop	Type	Default	Description
side	"top" | "right" | "bottom" | "left"	"bottom"	Preferred side of the trigger.
align	"start" | "center" | "end"	"center"	Alignment along the perpendicular axis.
sideOffset	number	4	Numeric offset along the side axis.
alignOffset	number	0	Numeric offset along the align axis.
avoidCollisions	boolean	true	Allow Radix to reposition to avoid viewport edges.
collisionPadding	number | Padding	0	Padding from viewport edges.

<PopoverAnchor>

Optional — overrides the positioning anchor. When omitted, the popover anchors to the <PopoverTrigger>.

<PopoverArrow>, <PopoverClose>, <PopoverPortal>

Direct re-exports of the Radix sub-components.

Implementation Notes

• The chassis NEVER assigns a numeric z-index — Radix portals handle stacking.
• <PopoverContent> self-portals via <PopoverPortal> so consumers do not need to compose the portal manually.
• align="center" and sideOffset={4} are chassis defaults (matching shadcn upstream) — overridable per call.
• data-side="<side>" is used by the cva animation classes — Radix sets it once positioning is resolved (which may differ from the requested side if avoidCollisions kicked in).
• For modal confirmation surfaces use <Dialog> or <AlertDialog> — Popover is intentionally non-modal so focus is NOT trapped.