Popover

Playground

Installation

pnpm add @tessinaui/ui

Usage

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeader,
  PopoverTitle,
  PopoverDescription,
  PopoverBody,
  PopoverFooter,
  PopoverArrow,
  PopoverClose,
} from "@tessinaui/ui";

<Popover size="md" rounded="md">
  <PopoverTrigger render={<Button>Open</Button>} />
  <PopoverContent side="bottom" align="center">
    <PopoverHeader showClose>
      <PopoverTitle>Popover title</PopoverTitle>
      <PopoverDescription>Brief description.</PopoverDescription>
    </PopoverHeader>
    <PopoverBody>
      <p>Any interactive content goes here — forms, lists, buttons…</p>
    </PopoverBody>
    <PopoverFooter>
      <PopoverClose render={<Button variant="ghost">Cancel</Button>} />
      <PopoverClose render={<Button>Confirm</Button>} />
    </PopoverFooter>
    <PopoverArrow />
  </PopoverContent>
</Popover>

Showcase

When to use Popover vs. Tooltip vs. DropdownMenu vs. Modal

Anatomy

Popover composes several parts. Only Popover, PopoverTrigger, and PopoverContent are required — everything else is optional.

<Popover>
  <PopoverTrigger>…</PopoverTrigger>
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle />
      <PopoverDescription />
    </PopoverHeader>
    <PopoverBody />
    <PopoverFooter />
    <PopoverArrow />
  </PopoverContent>
</Popover>

Size

Intent

Applies a semantic border colour to the popup and arrow — useful for warning/error confirmations.

Rounded

Positioning

PopoverContent accepts side (top | right | bottom | left), align (start | center | end), sideOffset (px gap from trigger, default 8), and alignOffset (px shift along the side, default 0).

<PopoverContent side="right" align="start" sideOffset={12}>
  …
</PopoverContent>

Arrow

The <PopoverArrow /> is a rotated square that blends into the popup surface, inheriting the current intent's border colour. It's entirely optional — omit it for a chip-style floating panel.

Backdrop & modal behaviour

By default the popover is non-modal — clicks outside dismiss but the page remains interactive. For destructive confirmations or flows that need focus-trapping, pass modal:

<Popover modal>
  …
</Popover>

To dim the background, render <PopoverBackdrop /> inside the popover:

<Popover modal>
  <PopoverTrigger render={<Button>Delete</Button>} />
  <PopoverBackdrop />
  <PopoverContent>…</PopoverContent>
</Popover>

Controlled

Popover accepts open, defaultOpen, and onOpenChange.

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

<Popover open={open} onOpenChange={setOpen}>
  <PopoverTrigger render={<Button>Open</Button>} />
  <PopoverContent>…</PopoverContent>
</Popover>

Close button in header

PopoverHeader accepts showClose — renders a small X button wired to close the popover. Only use when the popover is long-lived or contains interactive content that makes the dismiss affordance non-obvious.

<PopoverHeader showClose>
  <PopoverTitle>Rename file</PopoverTitle>
</PopoverHeader>

Accessibility

• The trigger and popup are linked via ARIA — screen readers announce the popup's content when it opens.
• PopoverTitle maps to aria-labelledby, PopoverDescription to aria-describedby.
• Focus moves to the first focusable element in the popup on open, and returns to the trigger on close.
• Escape closes the popover; outside-click closes it when dismissible is true (default).
• Use intent="error" for destructive confirmations so assistive tech surfaces the semantic colour via the rendered border.

RTL

Pass dir="rtl" to the root. PopoverHeader's close button, PopoverFooter actions, and alignment all flip to follow the reading direction.

<Popover dir="rtl">
  <PopoverTrigger render={<Button>فتح</Button>} />
  <PopoverContent side="bottom" align="start">…</PopoverContent>
</Popover>

API Reference

Popover (root)

PopoverContent

PopoverHeader

PopoverTrigger, PopoverClose

Render a <button>. Use render={<CustomElement />} to swap in a Button or any element. Standard Base UI render-prop pattern.

Sub-components

PopoverTitle, PopoverDescription, PopoverBody, PopoverFooter, PopoverBackdrop, PopoverArrow — all accept className and any HTML props.

Notes

• Built on @base-ui/react/popover — the same headless primitive used by the design system for tooltips and menus.
• Enter/exit animations use Base UI's data-[starting-style] and data-[ending-style] plus position-aware data-[side=*] attributes, so the popup "lifts off" from whichever side it opens on.
• The arrow is drawn as a single rotated square — no SVG — so it inherits the border colour automatically when intent changes.