Popover
⋯
Popover renders an interactive popup anchored to a trigger or custom point. Its composition and panel layout follow Kumo Popover, with Nesra semantic tokens for its surface, text, border, radius, and shadow. The Nesra Figma library has no generic Popover design.
Import Popover from @nesra/ui/popover or @nesra/ui.
import { Button } from "@nesra/ui/button";import { Popover } from "@nesra/ui/popover";
export function PopoverBasicExample() { return ( <Popover> <Popover.Trigger render={<Button variant="outline" />}>Open popover</Popover.Trigger> <Popover.Content> <Popover.Title>Report details</Popover.Title> <Popover.Description>Quarterly review is ready to share.</Popover.Description> </Popover.Content> </Popover> );}Composition
Section titled “Composition”Popover├── Popover.Trigger└── Popover.Content ├── Popover.Title ├── Popover.Description ├── interactive content └── Popover.CloseContent combines Base UI’s portal, positioner, and popup. Title names the popup;
Description adds explanatory text. Render a Close button when the user needs an explicit way
to finish or dismiss the content.
Examples
Section titled “Examples”With close button
Section titled “With close button”Popover.Close gives the user an explicit way to dismiss the popup and return focus to its trigger.
import { Button } from "@nesra/ui/button";import { Popover } from "@nesra/ui/popover";
export function PopoverWithCloseExample() { return ( <Popover> <Popover.Trigger render={<Button variant="outline" />}>Open settings</Popover.Trigger> <Popover.Content> <Popover.Title>Settings</Popover.Title> <Popover.Description>Configure your preferences here.</Popover.Description> <Popover.Close render={<Button className="mt-nesra-spacing-lg" size="sm" />}> Close </Popover.Close> </Popover.Content> </Popover> );}Interactive form
Section titled “Interactive form”The page owns form state and submission. This example copies the current report name into a draft when the popup opens, saves it on submit, and closes without saving on Cancel.
import { Button } from "@nesra/ui/button";import { Input } from "@nesra/ui/input";import { Popover } from "@nesra/ui/popover";import { useState, type SubmitEvent } from "react";
export function PopoverFormExample() { const [name, setName] = useState("Quarterly review"); const [draft, setDraft] = useState(name); const [open, setOpen] = useState(false);
function saveName(event: SubmitEvent<HTMLFormElement>) { event.preventDefault(); setName(draft.trim() || name); setOpen(false); }
return ( <div className="flex items-center gap-nesra-spacing-xl"> <span>{name}</span> <Popover onOpenChange={(nextOpen) => { if (nextOpen) setDraft(name); setOpen(nextOpen); }} open={open} > <Popover.Trigger render={<Button size="sm" variant="outline" />}>Rename</Popover.Trigger> <Popover.Content className="w-80"> <Popover.Title>Rename report</Popover.Title> <Popover.Description>Set the name shown in the report list.</Popover.Description> <form className="mt-nesra-spacing-lg" onSubmit={saveName}> <Input label="Report name" onChange={(event) => setDraft(event.currentTarget.value)} value={draft} /> <div className="mt-nesra-spacing-lg flex gap-nesra-spacing-md"> <Button size="sm" type="submit"> Save name </Button> <Popover.Close render={<Button size="sm" variant="outline" />}>Cancel</Popover.Close> </div> </form> </Popover.Content> </Popover> </div> );}Placements
Section titled “Placements”side sets the preferred side. Viewport collisions can move the popup.
import { Button } from "@nesra/ui/button";import { Popover } from "@nesra/ui/popover";
export function PopoverPlacementsExample() { return ( <div className="flex flex-wrap gap-nesra-spacing-xl p-nesra-spacing-3xl"> {(["bottom", "top", "left", "right"] as const).map((side) => ( <Popover key={side}> <Popover.Trigger render={<Button variant="outline" />}>{side}</Popover.Trigger> <Popover.Content side={side}> <Popover.Title>{side} placement</Popover.Title> <Popover.Description>The popup is positioned beside its trigger.</Popover.Description> </Popover.Content> </Popover> ))} </div> );}Custom content
Section titled “Custom content”Content can hold a custom layout. Set its width with className when the content needs a fixed
measure.
import { Button } from "@nesra/ui/button";import { Popover } from "@nesra/ui/popover";
export function PopoverCustomContentExample() { return ( <Popover> <Popover.Trigger render={<Button variant="outline" />}>User profile</Popover.Trigger> <Popover.Content className="w-64"> <div className="flex items-center gap-nesra-spacing-lg"> <span aria-hidden="true" className="flex size-10 shrink-0 items-center justify-center rounded-nesra-full bg-nesra-surface-card-bg-gray type-nesra-body-small-medium" > JD </span> <div> <Popover.Title>Jane Doe</Popover.Title> <Popover.Description>jane@example.com</Popover.Description> </div> </div> <div className="mt-nesra-spacing-lg border-t border-nesra-stroke-border pt-nesra-spacing-lg"> <Popover.Close render={<Button size="sm" variant="outline" />}> Close profile </Popover.Close> </div> </Popover.Content> </Popover> );}Open on hover
Section titled “Open on hover”Click is the default trigger. openOnHover also opens on pointer hover, with delay in
milliseconds. Keep a close control inside hover-triggered interactive content.
import { Button } from "@nesra/ui/button";import { Popover } from "@nesra/ui/popover";
export function PopoverHoverExample() { return ( <Popover> <Popover.Trigger delay={200} openOnHover render={<Button variant="outline" />}> Hover for details </Popover.Trigger> <Popover.Content> <Popover.Title>Report status</Popover.Title> <Popover.Description>The quarterly review is ready.</Popover.Description> <Popover.Close render={<Button className="mt-nesra-spacing-lg" size="sm" />}> Got it </Popover.Close> </Popover.Content> </Popover> );}Virtual anchor
Section titled “Virtual anchor”anchor positions the popup against an element or virtual point instead of the trigger. A
controlled popup can open without a Popover.Trigger. In that case, set finalFocus to the
control that opened it.
import { Button } from "@nesra/ui/button";import { Popover } from "@nesra/ui/popover";import { useRef, useState } from "react";
export function PopoverVirtualAnchorExample() { const buttonRef = useRef<HTMLButtonElement>(null); const labelRef = useRef<HTMLSpanElement>(null); const [anchorRect, setAnchorRect] = useState<DOMRect | null>(null);
return ( <div className="flex items-center gap-nesra-spacing-xl"> <span className="rounded-nesra-sm border border-nesra-stroke-border p-nesra-spacing-lg" ref={labelRef} > Quarterly review </span> <Button onClick={() => setAnchorRect(labelRef.current?.getBoundingClientRect() ?? null)} ref={buttonRef} size="sm" variant="outline" > Show details </Button> <Popover onOpenChange={(open) => !open && setAnchorRect(null)} open={anchorRect !== null}> <Popover.Content anchor={anchorRect ? { getBoundingClientRect: () => anchorRect } : undefined} finalFocus={buttonRef} side="bottom" > <Popover.Title>Quarterly review</Popover.Title> <Popover.Description>This popup is anchored to the report label.</Popover.Description> <Popover.Close render={<Button className="mt-nesra-spacing-lg" size="sm" />}> Close </Popover.Close> </Popover.Content> </Popover> </div> );}Light and Dark
Section titled “Light and Dark”Popover.Content uses --nesra-surface-popover-bg-neutral, --nesra-stroke-border, and
--nesra-text-body, so the panel follows the active theme. Popover.Description uses
--nesra-text-support. Trigger and close focus use shadow-nesra-focus-ring, which is gray-600 in
Light and gray-400 in Dark.
Accessibility
Section titled “Accessibility”Triggeropens on press and exposes expanded state. Give an icon-only trigger an accessible name.- Focus moves to the first tabbable element in
Contentby default. Escape, outside press, andClosedismiss the popup. Focus returns to the trigger after dismissal. Titlelabels the dialog. Use it unless the popup receives another accessible name. Label form fields inside the popup and handle form state and submission in the consuming page.- The default popup is non-modal. Set
modalonPopoveronly when page interaction must be restricted, and includePopover.Closeso keyboard and touch screen reader users can exit.
API reference
Section titled “API reference”Popover
Section titled “Popover”| Prop | Type | Default | Effect |
|---|---|---|---|
defaultOpen |
boolean |
false |
Initial uncontrolled state. |
open |
boolean |
— | Controlled open state. |
onOpenChange |
(open, eventDetails) => void |
— | Receives open and dismissal changes. |
modal |
boolean | "trap-focus" |
false |
Controls focus and outside behavior. |
Other Base UI Popover Root props are forwarded.
Popover.Trigger
Section titled “Popover.Trigger”Renders a button by default. render composes another button. disabled prevents opening.
openOnHover defaults to false; when enabled, delay defaults to 300ms and closeDelay
defaults to 0ms. Other Base UI Trigger props are forwarded.
Popover.Content
Section titled “Popover.Content”| Prop | Type | Default | Effect |
|---|---|---|---|
side |
"top" | "bottom" | "left" | "right" |
"bottom" |
Preferred side; collisions may flip it. |
align |
"start" | "center" | "end" |
"center" |
Preferred alignment. |
anchor |
Base UI anchor element, ref, or virtual anchor | trigger | Positions relative to another anchor. |
sideOffset |
number (px) |
4 |
Gap from the anchor. |
alignOffset |
number (px) |
0 |
Offset along the alignment axis. |
positionMethod |
"absolute" | "fixed" |
"absolute" |
CSS positioning method. |
collisionPadding |
Base UI padding | 12 |
Minimum viewport clearance. |
container |
Base UI portal container | document.body |
Portal destination. |
initialFocus |
Base UI focus target | first tabbable | Focus target after opening. |
finalFocus |
Base UI focus target | trigger | Focus target after closing. |
className |
string | state callback |
— | Popup classes. |
Other Base UI Positioner props are forwarded. Content has no fixed width. Its default panel has
16px horizontal and 12px vertical padding, an 8px radius, a border, a medium shadow, and a
150ms opacity transition that respects reduced motion. These follow Kumo’s panel pattern, mapped
to Nesra tokens. No Popover dimensions or states are specified in Nesra Figma.
Popover.Title, Popover.Description, and Popover.Close
Section titled “Popover.Title, Popover.Description, and Popover.Close”Each forwards the corresponding Base UI part props. Title renders an h2, Description a
paragraph, and Close a button by default. render can compose another element where the
underlying part allows it.
See colors and shape and elevation for token values.