- Vesyl UI

A floating panel anchored to a trigger and opened on click. Built on base-ui Popover — focus management, outside-press dismissal, and ARIA wiring come for free.

Reach for a Popover when the content is interactive (forms, toggles, a list of actions) and the user opens it deliberately. For passive, read-only preview content use HoverCard, which opens on hover; for a one-line hint on an element use Tooltip.

Compose three required parts: Popover (root, owns the open state), PopoverTrigger (the element that toggles it), and PopoverContent (the floating panel). The optional PopoverHeader, PopoverTitle, and PopoverDescription give the panel a labelled heading block and wire it to the panel for screen readers.

Basic

PopoverTrigger renders its own button by default, but most call sites hand it a Button (or any control) through the render prop so the trigger inherits our styles. PopoverContent portals to the end of the body and animates in from the trigger.

import {
  Button,
  HStack,
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@vesyl/ui-next";

export default function PopoverBasic() {
  return (
    <HStack justify="center">
      <Popover>
        <PopoverTrigger
          render={(props) => (
            <Button {...props} variant="outline">
              Shipping options
            </Button>
          )}
        />
        <PopoverContent align="start">
          <PopoverHeader>
            <PopoverTitle>Delivery preferences</PopoverTitle>
            <PopoverDescription>
              Choose how this order ships. Changes apply to the whole shipment,
              not individual parcels.
            </PopoverDescription>
          </PopoverHeader>
          <ul className="text-sm flex flex-col gap-1.5">
            <li>Ground · 3–5 business days</li>
            <li>Expedited · 2 business days</li>
            <li>Overnight · next business day</li>
          </ul>
        </PopoverContent>
      </Popover>
    </HStack>
  );
}

Positioning

PopoverContent accepts side (which edge of the trigger it anchors to) and align (how it lines up along that edge). sideOffset and alignOffset nudge it in pixels. Defaults are side="bottom", align="center", sideOffset={4} — the panel flips automatically when it would overflow the viewport.

import {
  Button,
  HStack,
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@vesyl/ui-next";

export default function PopoverPositioning() {
  return (
    <HStack gap={4} justify="center">
      <Popover>
        <PopoverTrigger
          render={(props) => (
            <Button {...props} variant="outline" size="sm">
              Top
            </Button>
          )}
        />
        <PopoverContent side="top" className="w-auto">
          <p className="text-sm">Anchored above the trigger.</p>
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger
          render={(props) => (
            <Button {...props} variant="outline" size="sm">
              Right · start
            </Button>
          )}
        />
        <PopoverContent side="right" align="start" sideOffset={8} className="w-auto">
          <p className="text-sm">Side right, aligned to the trigger's start edge.</p>
        </PopoverContent>
      </Popover>
      <Popover>
        <PopoverTrigger
          render={(props) => (
            <Button {...props} variant="outline" size="sm">
              Bottom · end
            </Button>
          )}
        />
        <PopoverContent side="bottom" align="end" className="w-auto">
          <p className="text-sm">Side bottom, aligned to the trigger's end edge.</p>
        </PopoverContent>
      </Popover>
    </HStack>
  );
}

Controlled

Popover is uncontrolled by default. To drive it yourself — e.g. to validate before opening, or to close it after a successful mutation — pass open and onOpenChange.

const [open, setOpen] = useState(false);

<Popover open={open} onOpenChange={setOpen}>
  <PopoverTrigger render={(props) => <Button {...props}>Edit parcel</Button>} />
  <PopoverContent>{/* … */}</PopoverContent>
</Popover>;

Reference

Root container; owns open state. Extends base-ui Popover.Root props.

Prop	Type	Default	Description
`defaultOpen`	`boolean`	`false`	Initial open state (uncontrolled)
`open`	`boolean`	—	Open state (controlled)
`onOpenChange`	`(open: boolean) => void`	—	Fires when the open state changes
`modal`	`boolean`	`false`	Trap focus and block interaction behind it

PopoverTrigger

The element that toggles the panel. Extends base-ui Popover.Trigger props.

Prop	Type	Default	Description
`render`	`ReactElement \| (props) => ReactElement`	—	Render your own trigger; spread `props` onto it

PopoverContent

The floating panel. Extends base-ui Popover.Popup props plus the positioner props below.

Prop	Type	Default	Description
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"bottom"`	Which edge of the trigger the panel anchors to
`align`	`"start" \| "center" \| "end"`	`"center"`	How the panel lines up along that edge
`sideOffset`	`number`	`4`	Gap in pixels between the trigger and the panel
`alignOffset`	`number`	`0`	Shift in pixels along the alignment axis
`className`	`string`	—	Merged onto the panel (default width is `w-72`)

PopoverHeader

Optional heading block — a flex column for the title and description. Renders a div; accepts standard div props.

PopoverTitle

The accessible heading for the panel. Extends base-ui Popover.Title props.

PopoverDescription

Supporting text below the title, wired to the panel as its accessible description. Extends base-ui Popover.Description props.