ui/components/popover

Popover

Floating content anchored to a trigger element. Supports click-to-open (popover) and hover (infotip) modes with built-in 4-side positioning, automatic flip, shift, and viewport collision detection without a third-party positioning dependency.

Preview

tsx

1 "use client";2 3 import { Popover } from "@/components/ui/popover";4 5 export default function PopoverBasicExample() {6   return (7     <Popover>8       <Popover.Trigger>9         {(triggerProps) => (10           <button11             {...triggerProps}12             type="button"13             className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"14           >15             click me16           </button>17         )}18       </Popover.Trigger>19       <Popover.Content role="dialog" aria-label="Popover actions" className="p-4 font-mono text-sm">20         <p className="text-foreground">Popover content with interactive elements.</p>21         <button22           type="button"23           className="mt-2 border border-foreground/30 px-2 py-0.5 text-xs focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"24         >25           action26         </button>27       </Popover.Content>28     </Popover>29   );30 }31

Installation

$pnpm exec dgadd add ui/popover

[Installs to]src/components/ui/popover[Item]ui/popover

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Package-mode consumers must install the required @diffgazer/keys peer alongside @diffgazer/ui. Copy and dgadd installs rewrite the autofocus helper to local source.

Usage

tsx

1 "use client";2 3 import { Popover } from "@/components/ui/popover";4 5 export default function PopoverBasicExample() {6   return (7     <Popover>8       <Popover.Trigger>9         {(triggerProps) => (10           <button11             {...triggerProps}12             type="button"13             className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"14           >15             click me16           </button>17         )}18       </Popover.Trigger>19       <Popover.Content role="dialog" aria-label="Popover actions" className="p-4 font-mono text-sm">20         <p className="text-foreground">Popover content with interactive elements.</p>21         <button22           type="button"23           className="mt-2 border border-foreground/30 px-2 py-0.5 text-xs focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"24         >25           action26         </button>27       </Popover.Content>28     </Popover>29   );30 }31

Examples

Hover Mode

Preview

tsx

1 import { Popover } from "@/components/ui/popover";2 3 export default function PopoverHoverExample() {4   return (5     <Popover triggerMode="hover" delayMs={300}>6       <Popover.Trigger>7         <span className="border-b border-dashed border-foreground/40 font-mono text-sm cursor-help">8           hover for info9         </span>10       </Popover.Trigger>11       <Popover.Content side="top" className="max-w-xs px-2 py-1 font-mono text-xs text-foreground">12         This field is required for validation.13       </Popover.Content>14     </Popover>15   );16 }17

Placement

Preview

tsx

1 "use client";2 3 import { Popover } from "@/components/ui/popover";4 5 export default function PopoverPlacementExample() {6   const sides = ["top", "bottom", "left", "right"] as const;7 8   return (9     <div className="flex flex-wrap items-center gap-4">10       {sides.map((side) => (11         <Popover key={side}>12           <Popover.Trigger>13             {(triggerProps) => (14               <button15                 {...triggerProps}16                 type="button"17                 className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"18               >19                 {side}20               </button>21             )}22           </Popover.Trigger>23           <Popover.Content side={side} className="px-3 py-2 font-mono text-xs text-foreground">24             Placed on {side}25           </Popover.Content>26         </Popover>27       ))}28     </div>29   );30 }31

Actions menu

Preview

tsx

1 "use client";2 3 import { Fragment, type KeyboardEvent, useState } from "react";4 import { Button } from "@/components/ui/button";5 import { Menu, MenuDivider, MenuItem } from "@/components/ui/menu";6 import { Popover } from "@/components/ui/popover";7 8 type ActionId = "copy" | "archive" | "delete";9 10 interface Action {11   id: ActionId;12   label: string;13   hotkey: string;14   /** Present when the current state cannot run the action; the entry stays listed, disabled. */15   disabledReason?: string;16 }17 18 const ACTIONS: Action[] = [19   { id: "copy", label: "Copy link", hotkey: "c" },20   { id: "archive", label: "Archive", hotkey: "a", disabledReason: "Already archived" },21   { id: "delete", label: "Delete", hotkey: "d" },22 ];23 24 /**25  * An actions menu behind one trigger: the trigger's aria-expanded carries the26  * open state, the menu takes focus on open, picking an entry closes it and27  * hands focus back to the trigger, and the destructive entry sits last behind28  * a divider. MenuItem's hotkey is a decorative label; Menu's onKeyDown binds it.29  */30 export default function PopoverMenu() {31   const [open, setOpen] = useState(false);32   const [lastAction, setLastAction] = useState<string | null>(null);33 34   const runAction = (id: ActionId) => {35     const action = ACTIONS.find((entry) => entry.id === id);36     if (!action || action.disabledReason) return;37     setOpen(false);38     setLastAction(action.label);39   };40 41   const runHotkey = (event: KeyboardEvent) => {42     if (event.altKey || event.ctrlKey || event.metaKey) return;43     const action = ACTIONS.find((entry) => !entry.disabledReason && entry.hotkey === event.key);44     if (!action) return;45     event.preventDefault();46     runAction(action.id);47   };48 49   return (50     <div className="flex flex-col items-start gap-3">51       <Popover open={open} onOpenChange={setOpen} popupRole="menu">52         <Popover.Trigger>53           {(triggerProps) => (54             // A trigger inside a roving-focus row would pass55             // `highlighted={rowHighlight && !open}`: aria-expanded already says the56             // menu is open, so the row's ring must not linger while the menu owns focus.57             <Button {...triggerProps} variant="outline" bracket>58               Actions <span aria-hidden="true">▾</span>59             </Button>60           )}61         </Popover.Trigger>62         <Popover.Content align="start" className="w-64 p-0">63           <Menu<ActionId>64             aria-label="Actions"65             autoFocus66             onClose={() => setOpen(false)}67             onSelect={runAction}68             onKeyDown={runHotkey}69           >70             {ACTIONS.map((action) => (71               <Fragment key={action.id}>72                 {action.id === "delete" ? <MenuDivider /> : null}73                 <MenuItem74                   id={action.id}75                   disabled={Boolean(action.disabledReason)}76                   variant={action.id === "delete" ? "danger" : "default"}77                   // A disabled entry advertises no key: it would do nothing here.78                   hotkey={action.disabledReason ? undefined : action.hotkey}79                 >80                   {action.label}81                   {action.disabledReason ? (82                     <span className="block text-2xs text-muted-foreground">83                       {action.disabledReason}84                     </span>85                   ) : null}86                 </MenuItem>87               </Fragment>88             ))}89           </Menu>90         </Popover.Content>91       </Popover>92       <p className="font-mono text-xs text-muted-foreground" aria-live="polite">93         {lastAction ? `Ran: ${lastAction}` : "Nothing run yet"}94       </p>95     </div>96   );97 }98

Controlled

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Popover } from "@/components/ui/popover";5 6 export default function PopoverControlledExample() {7   const [open, setOpen] = useState(false);8 9   return (10     <div className="flex items-center gap-4">11       <Popover open={open} onOpenChange={setOpen}>12         <Popover.Trigger>13           {(triggerProps) => (14             <button15               {...triggerProps}16               type="button"17               className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"18             >19               {open ? "close" : "open"}20             </button>21           )}22         </Popover.Trigger>23         <Popover.Content className="p-3 font-mono text-xs text-foreground">24           Controlled popover25           <button26             type="button"27             className="mt-2 block border border-foreground/30 px-2 py-0.5 text-xs focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"28             onClick={() => setOpen(false)}29           >30             dismiss31           </button>32         </Popover.Content>33       </Popover>34 35       <span className="font-mono text-xs text-foreground/60">36         state: {open ? "open" : "closed"}37       </span>38     </div>39   );40 }41

API Reference

Name	Type	Default	Description
open	boolean	—	Controlled open state. Pair with onOpenChange.
defaultOpen	boolean	false	Initial open state for uncontrolled mode.
onOpenChange	(open: boolean) => void	—	Fired when the open state changes.
triggerMode	"click" \| "hover"	"click"	Click toggles; hover delays pointer-open, keyboard focus opens immediately, and leave closes.
popupRole	"dialog" \| "menu" \| "listbox" \| "tree" \| "grid"	—	Overrides the aria-haspopup value applied to the trigger. Hover-mode tooltip content is selected by triggerMode, not popupRole.
enabled	boolean	true	When false, the popover never opens and trigger handlers are no-ops.
delayMs	number	500	Hover mode only. Delay before opening after pointer enter; keyboard focus opens immediately.
closeDelayMs	number	150 (hover) \| 0 (click)	Delay before closing after hover/focus leaves the trigger or content.
childrenrequired	ReactNode	—	Popover.Trigger and Popover.Content subparts.

Popover.Trigger

Name	Type	Default	Description
childrenrequired	ReactNode \| (props: PopoverTriggerRenderProps) => ReactNode	—	Trigger element. Pass a single element (cloned with merged ARIA/handlers), text (wrapped in <button>), or a render function for full control.

Name	Type	Default	Description
role	"dialog" \| "menu" \| "listbox" \| "tree" \| "grid" \| "tooltip"	—	Popup ARIA role. Defaults to "tooltip" in hover mode. A role="dialog" popup gains a fallback accessible name and is focusable when aria-label and aria-labelledby are both missing.
side	"top" \| "bottom" \| "left" \| "right"	"bottom"	Preferred side relative to the trigger.
align	"start" \| "center" \| "end"	"center"	Alignment along the chosen side.
sideOffset	number	6	Pixel gap from the trigger along the side axis.
alignOffset	number	0	Pixel offset along the alignment axis.
avoidCollisions	boolean	true	Flips to the opposite side, then cross-axis sides, then shifts within the viewport.
collisionPadding	number	8	Minimum gap between the content and the viewport edge during collision avoidance.
autoFocus	boolean	true	Dialog and menu roles only. When true, focuses the first focusable child on open (or the content itself for role="dialog" without a focusable child).
childrenrequired	ReactNode	—	Popover body content.

Data attributes

Attribute	Applies to	Values	Description
data-state	Popover.Content	"open" \| "closed"	Presence state forwarded by FloatingPanel for enter/exit animation styling.
data-side	Popover.Content	"top" \| "right" \| "bottom" \| "left"	Resolved side after collision handling.
data-align	Popover.Content	"start" \| "center" \| "end"	Resolved alignment after collision handling.
data-positioned	Popover.Content	present after first measurement	Marks content that has measured and can animate from its resolved origin.

Accessibility

Keyboard Navigation

Click-mode triggers toggle with pointer or keyboard activation. Escape closes open content and returns focus to the trigger. Dialog and menu content can auto-focus on open. Tab follows the browser's normal order; the popover stays open while focus moves between its trigger and content, then closes when focus leaves both.

Key	Action
Enter / Space	Toggles the trigger in click mode.
Escape	Closes open click-mode content and returns focus to the trigger.
Tab / Shift+Tab	Moves normally and closes click-mode content only after focus leaves the trigger/content pair.

Notes

Requires @diffgazer/keys (package mode)

Popover's auto-focus on open (focusing the first focusable element in the content) imports from the required @diffgazer/keys peer. Package consumers must install @diffgazer/keys with @diffgazer/ui; install both from npm (npm install @diffgazer/ui @diffgazer/keys), or take the component from the live registry instead (npx shadcn add https://r.b4r7.dev/r/ui/popover.json). Importing @diffgazer/ui/components/popover without keys fails at module load with an error naming the missing @diffgazer/keys package. Copy/dgadd consumers do not need the package — copy mode rewrites the focusable helper to local source.

Trigger Modes

Set `triggerMode="click"` (default) for interactive popovers that toggle on click. Set `triggerMode="hover"` for tooltip-like behavior with delay. Hover mode renders with `role="tooltip"` and content stays open while the pointer hovers it.

Positioning

Content is positioned relative to the trigger with `side` (top/bottom/left/right), `align` (start/center/end), `sideOffset`, and `alignOffset`. When `avoidCollisions` is true (default), content flips to the opposite side if it would overflow, then tries cross-axis sides, then shifts within the viewport.

Click Mode

In click mode, the popover toggles on trigger click, dismisses on outside click, Escape, or focus leaving the trigger/content pair. Content is interactive (pointer-events enabled). Use for forms, menus, or rich content.

Popup Role Contract

popupRole controls the trigger aria-haspopup value and accepts dialog, menu, listbox, tree, or grid. Hover mode content renders role="tooltip" automatically; tooltip is not a popupRole value. Consumers remain responsible for matching the role to the content pattern and supplying an accessible name for dialog-like content.

Controlled

Use `open` and `onOpenChange` props for controlled state. Works with both trigger modes.

Default Surface

Popover.Content ships the surface: a 1px --border hairline, a --surface-1 fill with a 1px --surface-1-highlight inner top lip, and the family's tight rounded-sm corners. --surface-1 sits one step off the page background (lighter in dark, darker in light), so a floating layer separates from dense content by depth step rather than by blur — there is still no drop shadow. There is no padding either, so menu-style content can sit flush. `className` merges last, so a consumer can override or drop any of it; FloatingPanel underneath stays fully headless.

Actions Menu

For a menu button, set popupRole="menu", give Popover.Content align="start" and no padding, and let Menu autoFocus with onClose closing the popover and onSelect closing it before running the pick; the popover then hands focus back to the trigger, whose aria-expanded carries the open state (a trigger sitting in a roving-focus row should drop its own highlight ring while open). MenuItem hotkey is a label only — bind the key in Menu onKeyDown, keep an entry the state cannot run listed and disabled with its reason instead of hiding it, and put the destructive entry last behind a MenuDivider. Inside the open menu ArrowUp/ArrowDown move the highlight and ArrowLeft/ArrowRight are inert (they only serve submenus); Escape and Tab close it. See the "Actions menu" example.

Portal Rendering

Content renders through the shared Portal primitive. When a PortalContainerProvider is present, Popover.Content uses that scoped container; otherwise it falls back to document.body. This keeps nested overlay trees in the same portal scope while still escaping overflow:hidden ancestors by default.

When role="dialog" is used without aria-label or aria-labelledby, the content falls back to the accessible name "Popover" so assistive technology never sees an unlabeled dialog. Provide your own label for any production usage; the fallback exists to prevent silent accessibility regressions during development.

Source

Install via CLI: pnpm exec dgadd add ui/popover. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Popover

Installation

Usage

Examples

Hover Mode

Placement

Actions menu

Controlled

API Reference

Popover

Popover.Trigger

Popover.Content

Data attributes

Accessibility

Keyboard Navigation

Notes

Requires @diffgazer/keys (package mode)

Trigger Modes

Positioning

Click Mode

Popup Role Contract

Controlled

Default Surface

Actions Menu

Portal Rendering

Source

View component source (30 files)