Popover

import { Button } from "@/components/ui/button";
import { NumberField } from "@/components/ui/number-field";
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";

export default function PopoverDemo() {
  return (
    <PopoverTrigger>
      <Button variant="outline">Dimensions</Button>
      <Popover>
        <PopoverDialog className="grid gap-4">
          <div className="grid gap-1.5">
            <PopoverTitle>Dimensions</PopoverTitle>
            <p className="text-muted-foreground text-sm">
              Set the size of the selected layer.
            </p>
          </div>
          <div className="grid grid-cols-2 gap-2">
            <NumberField label="Width" defaultValue={1200} minValue={1} />
            <NumberField label="Height" defaultValue={630} minValue={1} />
          </div>
        </PopoverDialog>
      </Popover>
    </PopoverTrigger>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/popover

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";

tsx

<PopoverTrigger>
  <Button>Open</Button>
  <Popover>
    <PopoverDialog>
      <PopoverTitle>Title</PopoverTitle>
      {/* content */}
    </PopoverDialog>
  </Popover>
</PopoverTrigger>

PopoverTrigger connects the first child (any pressable, usually a Button) to the Popover after it. Popover is the positioned surface; PopoverDialog adds padding and dialog semantics so focus moves in and the content is announced.

Always wrap content in PopoverDialog

Popover on its own is just a positioned container. That's what Menu and Select build on, because they bring their own roles. For anything else, put a PopoverDialog inside and name it with a PopoverTitle or an aria-label.

When to use

Popover — small, interactive content tied to a specific control: a quick form, a share panel, a detail card, a notification list.
Tooltip — a short, non-interactive label shown on hover or focus.
Menu — a list of actions.
Dialog — a task that needs the user's full attention, or content too large for a popover.
Sheet — longer secondary content that slides in from an edge.

Anatomy

tsx

<PopoverTrigger>
  <Button />                {/* trigger */}
  <Popover>                 {/* positioned surface, optional arrow */}
    <PopoverDialog>         {/* role="dialog", padding, focus management */}
      <PopoverTitle />      {/* accessible name */}
    </PopoverDialog>
  </Popover>
</PopoverTrigger>

Part	Renders	Notes
`PopoverTrigger`	—	Manages open state and wires the trigger to the popover. Same component as `DialogTrigger`.
`Popover`	`<div>` (portal)	Positioned surface with border, shadow and enter/exit animations. Renders an `OverlayArrow` when `showArrow` is set.
`PopoverDialog`	`<div role="dialog">`	Content wrapper with `w-72 p-4`. Receives focus on open.
`PopoverTitle`	`Heading` (`slot="title"`, `<h2>`)	Becomes the dialog's accessible name.

Examples

With arrow

showArrow adds an arrow that points at the trigger and rotates with the placement. The default offset grows from 4px to 10px to make room for it. Arrows help most when the trigger is small, like an info icon.

Monthly active users

import { InfoIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTrigger,
} from "@/components/ui/popover";

export default function PopoverArrow() {
  return (
    <div className="flex items-center gap-1.5 text-sm">
      Monthly active users
      <PopoverTrigger>
        <Button variant="ghost" size="icon-xs" aria-label="About this metric">
          <InfoIcon />
        </Button>
        <Popover showArrow placement="top">
          <PopoverDialog
            aria-label="About monthly active users"
            className="w-64 text-sm"
          >
            Unique users who signed in at least once in the last 30 days. Bots
            and service accounts are excluded.
          </PopoverDialog>
        </Popover>
      </PopoverTrigger>
    </div>
  );
}

Placement

placement sets the preferred side and alignment: top, bottom, left, right, start, end, plus combinations like bottom start or top end. The default is bottom. When there isn't room, the popover flips to the opposite side (disable with shouldFlip={false}).

import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTrigger,
} from "@/components/ui/popover";

const placements = ["top", "right", "bottom", "left"] as const;

export default function PopoverPlacement() {
  return (
    <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
      {placements.map((placement) => (
        <PopoverTrigger key={placement}>
          <Button variant="outline" className="capitalize">
            {placement}
          </Button>
          <Popover placement={placement} showArrow>
            <PopoverDialog
              aria-label={`Popover on ${placement}`}
              className="w-auto px-3 py-2 text-sm"
            >
              Placed on the {placement}
            </PopoverDialog>
          </Popover>
        </PopoverTrigger>
      ))}
    </div>
  );
}

Forms

PopoverDialog accepts a render function, ({ close }) => …. Wrap a React Aria Form in it to validate the fields and close the popover after a successful submit.

import { LinkIcon } from "lucide-react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";
import { TextField } from "@/components/ui/text-field";
import { toast } from "@/components/ui/toast";

export default function PopoverForm() {
  return (
    <PopoverTrigger>
      <Button variant="outline">
        <LinkIcon /> Insert link
      </Button>
      <Popover placement="bottom start">
        <PopoverDialog className="w-80">
          {({ close }) => (
            <Form
              className="grid gap-3"
              onSubmit={(e) => {
                e.preventDefault();
                const url = new FormData(e.currentTarget).get("url");
                close();
                toast.success(`Linked to ${url}`);
              }}
            >
              <PopoverTitle>Insert link</PopoverTitle>
              <TextField
                label="URL"
                name="url"
                type="url"
                isRequired
                autoFocus
                placeholder="https://"
              />
              <TextField
                label="Text to display"
                name="text"
                placeholder="Optional"
              />
              <div className="flex justify-end gap-2">
                <Button variant="ghost" size="sm" onPress={close}>
                  Cancel
                </Button>
                <Button type="submit" size="sm">
                  Insert
                </Button>
              </div>
            </Form>
          )}
        </PopoverDialog>
      </Popover>
    </PopoverTrigger>
  );
}

Controlled

Pass isOpen and onOpenChange to PopoverTrigger to own the open state, for example to close the popover after a choice or to open it from code.

Status

import {
  CheckIcon,
  CircleDashedIcon,
  CircleDotIcon,
  CircleIcon,
} from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTrigger,
} from "@/components/ui/popover";

const statuses = [
  { id: "backlog", label: "Backlog", icon: CircleDashedIcon },
  { id: "todo", label: "Todo", icon: CircleIcon },
  { id: "progress", label: "In progress", icon: CircleDotIcon },
  { id: "done", label: "Done", icon: CheckIcon },
];

export default function PopoverControlled() {
  const [isOpen, setOpen] = useState(false);
  const [status, setStatus] = useState(statuses[2]);
  return (
    <div className="flex items-center gap-3 text-sm">
      <span className="text-muted-foreground">Status</span>
      <PopoverTrigger isOpen={isOpen} onOpenChange={setOpen}>
        <Button variant="outline" size="sm">
          <status.icon /> {status.label}
        </Button>
        <Popover placement="bottom start">
          <PopoverDialog aria-label="Change status" className="w-48 p-1">
            <div className="grid">
              {statuses.map((s) => (
                <Button
                  key={s.id}
                  variant="ghost"
                  size="sm"
                  className="justify-start"
                  onPress={() => {
                    setStatus(s);
                    setOpen(false);
                  }}
                >
                  <s.icon /> {s.label}
                  {s.id === status.id && <CheckIcon className="ml-auto" />}
                </Button>
              ))}
            </div>
          </PopoverDialog>
        </Popover>
      </PopoverTrigger>
    </div>
  );
}

Custom anchor

Use Popover without a trigger by passing triggerRef, isOpen and onOpenChange. It then positions itself relative to any element, here a field, while a separate link opens it.

Webhook secret

import { useRef, useState } from "react";
import { Button } from "@/components/ui/button";
import { Popover, PopoverDialog, PopoverTitle } from "@/components/ui/popover";
import { TextField } from "@/components/ui/text-field";

export default function PopoverTriggerRef() {
  const fieldRef = useRef<HTMLDivElement>(null);
  const [isOpen, setOpen] = useState(false);
  return (
    <div className="grid w-full max-w-xs gap-2">
      <div ref={fieldRef}>
        <TextField
          label="Webhook secret"
          defaultValue="whsec_6f2c1e9a"
          isReadOnly
        />
      </div>
      <Button
        variant="link"
        size="sm"
        className="justify-self-start px-0"
        onPress={() => setOpen(true)}
      >
        Where do I use this?
      </Button>
      <Popover
        triggerRef={fieldRef}
        isOpen={isOpen}
        onOpenChange={setOpen}
        placement="bottom start"
        showArrow
      >
        <PopoverDialog className="grid gap-2 text-sm">
          <PopoverTitle>Verifying webhooks</PopoverTitle>
          <p className="text-muted-foreground">
            Compare this secret with the signature in the{" "}
            <code className="font-mono text-foreground text-xs">
              X-Signature
            </code>{" "}
            header of every request we send.
          </p>
        </PopoverDialog>
      </Popover>
    </div>
  );
}

Rich content

Any pressable can be the trigger, like an inline name that opens a profile card with an Avatar, a Badge and actions. Popovers open on press, not hover, so the content stays reachable for keyboard and touch users.

Reviewed by two days ago and approved the migration plan for the ledger service.

import { MailIcon, MapPinIcon, MessageSquareIcon } from "lucide-react";
import { Button as AriaButton } from "react-aria-components";
import { Avatar } from "@/components/ui/avatar";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";

export default function PopoverProfileCard() {
  return (
    <p className="max-w-sm text-sm leading-relaxed">
      Reviewed by{" "}
      <PopoverTrigger>
        <AriaButton className="rounded-xs font-medium text-brand underline-offset-4 outline-none data-focus-visible:ring-[3px] data-focus-visible:ring-ring/25 data-hovered:underline">
          Elena Novak
        </AriaButton>
        <Popover placement="bottom start">
          <PopoverDialog className="grid w-72 gap-3">
            <div className="flex items-start gap-3">
              <Avatar
                size="lg"
                alt="Elena Novak"
                fallback="EN"
                colorful
                status="online"
              />
              <div className="min-w-0 flex-1">
                <PopoverTitle>Elena Novak</PopoverTitle>
                <p className="mt-1 text-muted-foreground text-xs">
                  Staff engineer · Payments
                </p>
              </div>
              <Badge size="sm" color="success">
                Available
              </Badge>
            </div>
            <ul className="grid gap-1.5 text-muted-foreground text-xs">
              <li className="flex items-center gap-2">
                <MapPinIcon className="size-3.5" /> Lisbon · 14:32 local time
              </li>
              <li className="flex items-center gap-2">
                <MailIcon className="size-3.5" /> elena.novak@acme.dev
              </li>
            </ul>
            <div className="grid grid-cols-2 gap-2">
              <Button variant="outline" size="sm">
                View profile
              </Button>
              <Button size="sm">
                <MessageSquareIcon /> Message
              </Button>
            </div>
          </PopoverDialog>
        </Popover>
      </PopoverTrigger>{" "}
      two days ago and approved the migration plan for the ledger service.
    </p>
  );
}

Recipes

A copyable link, a Select for access level and an AvatarGroup of collaborators. Nested overlays like the select work inside a popover; Esc closes the innermost one first.

import {
  CheckIcon,
  CopyIcon,
  GlobeIcon,
  LockIcon,
  Share2Icon,
} from "lucide-react";
import { useState } from "react";
import type { Key } from "react-aria-components";
import { Avatar, AvatarGroup } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";
import { Select, SelectItem } from "@/components/ui/select";
import { Separator } from "@/components/ui/separator";
import { TextField } from "@/components/ui/text-field";

const url = "https://acme.design/f/Q3-launch-plan";

export default function PopoverRecipeShare() {
  const [access, setAccess] = useState<Key | null>("team");
  const [copied, setCopied] = useState(false);

  const copy = async () => {
    await navigator.clipboard?.writeText(url).catch(() => {});
    setCopied(true);
    setTimeout(() => setCopied(false), 1500);
  };

  return (
    <PopoverTrigger>
      <Button>
        <Share2Icon /> Share
      </Button>
      <Popover placement="bottom end">
        <PopoverDialog className="grid w-80 gap-4">
          <div className="grid gap-1.5">
            <PopoverTitle>Share “Q3 launch plan”</PopoverTitle>
            <p className="text-muted-foreground text-xs">
              Anyone with access can view and comment.
            </p>
          </div>
          <div className="flex items-end gap-2">
            <TextField
              aria-label="Share link"
              value={url}
              isReadOnly
              size="sm"
              className="min-w-0 flex-1"
            />
            <Button
              variant="outline"
              size="icon-sm"
              aria-label={copied ? "Copied" : "Copy link"}
              onPress={copy}
            >
              {copied ? <CheckIcon className="text-success" /> : <CopyIcon />}
            </Button>
          </div>
          <Select
            label="General access"
            size="sm"
            selectedKey={access}
            onSelectionChange={setAccess}
            prefix={access === "public" ? <GlobeIcon /> : <LockIcon />}
          >
            <SelectItem id="restricted">Only invited people</SelectItem>
            <SelectItem id="team">Anyone at Acme</SelectItem>
            <SelectItem id="public">Anyone with the link</SelectItem>
          </Select>
          <Separator />
          <div className="flex items-center justify-between gap-3">
            <AvatarGroup size="sm" max={4}>
              <Avatar size="sm" alt="Jin Park" fallback="JP" colorful />
              <Avatar size="sm" alt="Nora Ali" fallback="NA" colorful />
              <Avatar size="sm" alt="Sam Ortiz" fallback="SO" colorful />
              <Avatar size="sm" alt="Ivy Chen" fallback="IC" colorful />
              <Avatar size="sm" alt="Tom Reyes" fallback="TR" colorful />
            </AvatarGroup>
            <span className="text-muted-foreground text-xs">
              5 people have access
            </span>
          </div>
        </PopoverDialog>
      </Popover>
    </PopoverTrigger>
  );
}

Notifications

An icon button with an unread count opens a scrollable list with "Mark all read". The trigger's aria-label includes the count, since the badge is visual only. p-0 on PopoverDialog lets the header and list run edge to edge.

import { BellIcon, CheckCheckIcon } from "lucide-react";
import { useState } from "react";
import { Avatar } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";
import { cn } from "@/lib/utils";

const initial = [
  {
    id: 1,
    name: "Kofi Mensah",
    initials: "KM",
    text: "commented on Pricing page redesign",
    time: "4m",
    unread: true,
  },
  {
    id: 2,
    name: "Laura Weiss",
    initials: "LW",
    text: "assigned you to Fix invoice rounding",
    time: "1h",
    unread: true,
  },
  {
    id: 3,
    name: "Diego Rossi",
    initials: "DR",
    text: "merged #1289 into main",
    time: "3h",
    unread: true,
  },
  {
    id: 4,
    name: "Hana Sato",
    initials: "HS",
    text: "invited you to Growth experiments",
    time: "Yesterday",
    unread: false,
  },
];

export default function PopoverRecipeNotifications() {
  const [items, setItems] = useState(initial);
  const unread = items.filter((n) => n.unread).length;
  return (
    <PopoverTrigger>
      <Button
        variant="outline"
        size="icon"
        aria-label={
          unread ? `Notifications, ${unread} unread` : "Notifications"
        }
        className="relative"
      >
        <BellIcon />
        {unread > 0 && (
          <span className="absolute -top-1 -right-1 flex h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1 font-medium text-[0.625rem] text-white tabular-nums">
            {unread}
          </span>
        )}
      </Button>
      <Popover placement="bottom end">
        <PopoverDialog className="w-80 p-0">
          <div className="flex items-center justify-between border-b px-4 py-3">
            <PopoverTitle>Notifications</PopoverTitle>
            <Button
              variant="link"
              size="xs"
              className="h-auto px-0"
              isDisabled={unread === 0}
              onPress={() =>
                setItems((list) => list.map((n) => ({ ...n, unread: false })))
              }
            >
              <CheckCheckIcon /> Mark all read
            </Button>
          </div>
          <ul className="max-h-72 divide-y overflow-y-auto">
            {items.map((n) => (
              <li
                key={n.id}
                className={cn(
                  "flex gap-3 px-4 py-3 text-sm",
                  n.unread && "bg-brand/5",
                )}
              >
                <Avatar size="sm" alt={n.name} fallback={n.initials} colorful />
                <div className="min-w-0 flex-1">
                  <p className="leading-snug">
                    <span className="font-medium">{n.name}</span> {n.text}
                  </p>
                  <p className="mt-0.5 text-muted-foreground text-xs">
                    {n.time}
                  </p>
                </div>
                {n.unread && (
                  <span className="mt-1.5 size-2 shrink-0 rounded-full bg-brand" />
                )}
              </li>
            ))}
          </ul>
          <div className="border-t p-2">
            <Button variant="ghost" size="sm" className="w-full">
              View all notifications
            </Button>
          </div>
        </PopoverDialog>
      </Popover>
    </PopoverTrigger>
  );
}

Feedback form

A small form with a TextareaField and an emoji ToggleButtonGroup. The submit button shows isPending while the request runs, then the popover closes and a toast confirms.

import {
  AngryIcon,
  FrownIcon,
  LaughIcon,
  MessageSquareHeartIcon,
  SmileIcon,
} from "lucide-react";
import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";
import { TextareaField } from "@/components/ui/textarea";
import { toast } from "@/components/ui/toast";
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";

const moods = [
  { id: "angry", label: "Very unhappy", icon: AngryIcon },
  { id: "sad", label: "Unhappy", icon: FrownIcon },
  { id: "happy", label: "Happy", icon: SmileIcon },
  { id: "delighted", label: "Delighted", icon: LaughIcon },
];

export default function PopoverRecipeFeedback() {
  const [pending, setPending] = useState(false);
  return (
    <PopoverTrigger>
      <Button variant="outline" size="sm">
        <MessageSquareHeartIcon /> Feedback
      </Button>
      <Popover placement="bottom end">
        <PopoverDialog className="w-80">
          {({ close }) => (
            <Form
              className="grid gap-3"
              onSubmit={async (e) => {
                e.preventDefault();
                setPending(true);
                await new Promise((r) => setTimeout(r, 800));
                setPending(false);
                close();
                toast.success("Thanks! Your feedback was sent to the team.");
              }}
            >
              <PopoverTitle>Send feedback</PopoverTitle>
              <TextareaField
                aria-label="Feedback"
                name="message"
                rows={4}
                isRequired
                autoFocus
                placeholder="What's working, and what isn't?"
              />
              <div className="flex items-center justify-between gap-2">
                <ToggleButtonGroup
                  variant="spaced"
                  size="sm"
                  aria-label="How do you feel?"
                >
                  {moods.map((m) => (
                    <ToggleButton key={m.id} id={m.id} aria-label={m.label}>
                      <m.icon />
                    </ToggleButton>
                  ))}
                </ToggleButtonGroup>
                <Button type="submit" size="sm" isPending={pending}>
                  Send
                </Button>
              </div>
            </Form>
          )}
        </PopoverDialog>
      </Popover>
    </PopoverTrigger>
  );
}

Accessibility

PopoverDialog renders role="dialog". Focus moves into the popover on open (to an element with autoFocus, otherwise the popover itself) and returns to the trigger on close.
Name the dialog with PopoverTitle or aria-label. Without either, React Aria falls back to labelling it by the trigger.
The trigger gets aria-expanded and aria-controls, so screen readers announce that it opens a dialog.
Popovers are modal for assistive tech: content outside is hidden from screen readers while open. isNonModal turns this off, but only use it for patterns designed for it.
Clicking outside or pressing Esc closes the popover.

Keyboard

Key	Action
`Space` / `Enter`	Opens the popover from the trigger
`Tab` / `Shift`+`Tab`	Moves focus through the popover's content
`Esc`	Closes the popover and returns focus to the trigger

Styling

Data attributes

On the Popover:

Attribute	Present when
`data-placement`	Always: the resolved side, `"top"`, `"bottom"`, `"left"` or `"right"` (after flipping)
`data-trigger`	Set to the component that opened it, e.g. `"DialogTrigger"`, `"MenuTrigger"` or `"Select"`
`data-entering`	Opening animation is running
`data-exiting`	Closing animation is running
`data-slot="popover"`	Always

PopoverDialog has data-slot="popover-dialog" and PopoverTitle has data-slot="popover-title".

CSS variables

Variable	Value
`--trigger-width`	Width of the trigger, e.g. `min-w-(--trigger-width)` to match it
`--trigger-anchor-point`	The point on the trigger the popover is anchored to, useful as a `transform-origin`

Customizing

className on Popover styles the surface; className on PopoverDialog sets the width and padding (defaults w-72 p-4).
The slide direction of the enter animation follows data-placement, so the popover always grows away from its trigger.
popoverStyles is exported: the class string for the surface (border, background, shadow, animations). Reuse it for custom floating elements.

tsx

import { popoverStyles } from "@/components/ui/popover";

Render props

className and children on Popover accept a function of its state:

tsx

<Popover className={({ placement }) => (placement === "top" ? "mb-1" : "")}>
  …
</Popover>

API Reference

PopoverTrigger

Prop

Type

Prop

Type

Also accepts every prop of React Aria's Popover.

PopoverDialog

Prop

Type

Also accepts every prop of React Aria's Dialog.

PopoverTitle

Accepts every prop of React Aria's Heading, including level to change the heading element (<h2> inside a dialog).

Tooltip — a short label on hover or focus.
Menu — a list of actions in a popover.
Dialog — a centered modal for focused tasks.
Date Picker — a calendar in a popover.