# Popover
> Show supporting information or controls in a non-modal popup.
Source: https://www.honestui.com/docs/components/popover
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import { Field } from "@/components/honest-ui/ui/field"
import { Form } from "@/components/honest-ui/ui/form"
import {
Popover,
PopoverDescription,
PopoverPopup,
PopoverTitle,
PopoverTrigger,
} from "@/components/honest-ui/ui/popover"
import { Textarea } from "@/components/honest-ui/ui/textarea"
export function PopoverDemo() {
return (
}>
Open Popover
Send us feedback
Let us know how we can improve.
)
}
```
## Overview [#overview]
Use a Popover for contextual content that appears near a trigger when the person asks for it: lightweight forms, explanations, filters, small pickers, and secondary controls that would crowd the page if they were always visible.
A popover is deliberately opened, so it can hold interactive controls — unlike a Tooltip, which disappears as soon as focus moves and should never contain anything a person needs to operate. When the task needs the rest of the page blocked or a larger workflow, use Dialog instead; a popover is non-modal by default and lets people keep working while it is open.
## Anatomy [#anatomy]
A popover has a trigger, popup, optional title, optional description, content, and an optional close action. `PopoverPopup` renders the portal and positioner internally, so positioning props like `side` and `align` sit directly on it. The title names what opened; the description carries supporting context. Both wire into the popup's accessible name automatically when present.
## Behavior [#behavior]
**Opening.** Clicking the trigger opens the popup and moves focus into it — to the first tabbable control inside, or to the popup itself when there is nothing tabbable. If it was opened by touch, the popup element receives focus so the on-screen keyboard does not pop open over content nobody can see yet.
**While open.** The default mode is non-modal: Tab walks through the popup's controls and then continues back into the page. Pressing Escape closes it, and clicking outside closes it too. Set `modal` on the root to `"trap-focus"` (focus cycles inside but the page stays scrollable) or `true` (interaction limited to the popup and page scroll locked) when the content must be dealt with before continuing.
**Closing.** Focus returns to the trigger, so keyboard users continue where they left off. Pass `finalFocus` on the popup to send focus somewhere else.
**Positioning.** `side` places the popup relative to the trigger (`bottom` by default), `align` sets alignment within that side, and `sideOffset` adds distance. When there is no room, the popup flips to the opposite side or shifts sideways to stay in the viewport, and its height never exceeds the available viewport space. The positioner forwards Base UI's full set of collision options if you need finer control.
## Accessibility [#accessibility]
The popup gets `role="dialog"`. Its accessible name comes from `PopoverTitle` and its description from `PopoverDescription`, so include both whenever the content needs context — an unlabeled dialog is announced as just "dialog". The trigger keeps its own name and state (`aria-expanded`), which is why the trigger text should describe what opens.
Everything dismissible by mouse is dismissible by keyboard: Escape always works, and moving focus outside the popup closes it. Because focus returns to the trigger on close, a popover is safe to open from the keyboard mid-task.
Colors come from theme tokens, so the popup adapts to dark mode automatically. Padding uses logical properties, so the layout mirrors in right-to-left locales. Content wraps inside the popup's capped width rather than overflowing; very long text grows the popup vertically up to the viewport limit before scrolling becomes your responsibility to style.
## Installation [#installation]
Install the following dependencies:
```bash
npm install @base-ui-components/react
```
Copy and paste the following code into your project.
### components/ui/popover.tsx
```tsx
"use client"
import { Popover as PopoverPrimitive } from "@base-ui-components/react/popover"
import { cn } from "@/lib/utils"
const Popover = PopoverPrimitive.Root
function PopoverTrigger(props: PopoverPrimitive.Trigger.Props) {
return
}
function PopoverPopup({
children,
className,
side = "bottom",
align = "center",
sideOffset = 4,
...props
}: PopoverPrimitive.Popup.Props & {
side?: PopoverPrimitive.Positioner.Props["side"]
align?: PopoverPrimitive.Positioner.Props["align"]
sideOffset?: PopoverPrimitive.Positioner.Props["sideOffset"]
}) {
return (
{children}
)
}
function PopoverClose({ ...props }: PopoverPrimitive.Close.Props) {
return
}
function PopoverTitle({ className, ...props }: PopoverPrimitive.Title.Props) {
return (
)
}
function PopoverDescription({
className,
...props
}: PopoverPrimitive.Description.Props) {
return (
)
}
export {
Popover,
PopoverTrigger,
PopoverPopup,
PopoverPopup as PopoverContent,
PopoverTitle,
PopoverDescription,
PopoverClose,
}
```
Update the import paths to match your project setup.
## Usage [#usage]
```tsx
import {
Popover,
PopoverClose,
PopoverDescription,
PopoverPopup,
PopoverTitle,
PopoverTrigger,
} from "@/components/ui/popover";
```
```tsx
View keyboard shortcutsKeyboard shortcutsPress Command and K to open search.Close
```
`PopoverContent` is an alias of `PopoverPopup`. Use controlled state (`open` / `onOpenChange` on the root) only when something else must own whether the popover is visible.
## Don't do this [#dont-do-this]
### Confirming destructive actions in a popover [#confirming-destructive-actions-in-a-popover]
```tsx
// Bad
Delete project?
```
```tsx
// Good
}>
Delete project
Delete Aurora website?
This permanently removes the site and all deployments.
}>
Cancel
```
A popover closes on any outside click, which means a stray click can silently cancel a confirmation — or worse, leave someone unsure whether the action ran. Destructive confirmations need a modal surface that interrupts, states the consequence, and cannot be dismissed by accident. That is AlertDialog's job.
### Omitting the title [#omitting-the-title]
```tsx
// Bad
```
```tsx
// Good
Opacity
```
The popup is announced as a dialog, and its name comes from the title. Without one, screen-reader users hear "dialog" with no indication of what it controls. A visually hidden title still provides the name if the design has none.
### Opening on hover to fake a tooltip [#opening-on-hover-to-fake-a-tooltip]
```tsx
// Bad
Details
```
```tsx
// Good
DetailsShows archived projects too.
```
A hover-opened popup appears under the cursor without being asked for, swallows clicks meant for nearby content, and lingers unpredictably. Text hints belong in Tooltips, which are tuned for hover and focus with delays and instant grouping; Popovers are for content people choose to open.
## Examples [#examples]
### With Close Button [#with-close-button]
An explicit close action plus a corner dismiss button. Escape and outside clicks work regardless.
```tsx
import { X as XIcon } from "honestui/icons"
import { Button } from "@/components/honest-ui/ui/button"
import {
Popover,
PopoverClose,
PopoverDescription,
PopoverPopup,
PopoverTitle,
PopoverTrigger,
} from "@/components/honest-ui/ui/popover"
export function PopoverWithCloseDemo() {
return (
}>
Open Popover
Close
Notifications
You are all caught up. Good job!
}>
Close
)
}
```
### Account summary [#account-summary]
Read-only detail revealed on demand, with title and description providing the accessible name.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import { Popover, PopoverDescription, PopoverPopup, PopoverTitle, PopoverTrigger } from "@/components/honest-ui/ui/popover"
export function PopoverAccountSummary() {
return (
}>Account
Acme workspace12 members, 4 active projects, and 84% storage used.
)
}
```
### Small picker [#small-picker]
Compact choice sets fit a popover well. Larger pickers deserve a Dialog or their own route.
```tsx
import { Button } from "@/components/honest-ui/ui/button"
import { Popover, PopoverPopup, PopoverTitle, PopoverTrigger } from "@/components/honest-ui/ui/popover"
const colors = ["bg-blue-500", "bg-emerald-500", "bg-amber-500", "bg-rose-500"]
export function PopoverColorSwatch() {
return (
}>Pick color
Label color
{colors.map((color) => )}
)
}
```
## API reference [#api-reference]
All parts forward their matching Base UI Popover props. Honest UI adds positioning shortcuts on `PopoverPopup`:
| Prop | Values | Default |
| ------------ | --------------------------------------------------------------- | -------- |
| `side` | `top`, `right`, `bottom`, `left`, and logical `inline` variants | `bottom` |
| `align` | `start`, `center`, `end` | `center` |
| `sideOffset` | number | `4` |
The root accepts `open` / `onOpenChange` for controlled usage and `modal={false | 'trap-focus' | true}` (`false` by default). The popup accepts `initialFocus` and `finalFocus` to direct where focus lands on open and close. `PopoverContent` aliases `PopoverPopup`.
See the [Base UI Popover API](https://base-ui.com/react/components/popover#api-reference).