# Popover

A popup that displays content anchored to a trigger.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="popover" />

<ComponentPreview name="popover" title="popover.tsx">
<PopoverDemo />
</ComponentPreview>

A floating panel anchored to a trigger. Opens on trigger click, closes on outside click or `Escape`. Position is resolved by Floating UI, so the panel flips and shifts automatically when it would overflow the viewport.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add popover
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install @floating-ui/react-dom
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="popover" title="components/ui/popover.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="popover.tsx"
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";
```

```tsx title="popover.tsx"
<Popover>
  <PopoverTrigger as={Button} variant="outline">Open</PopoverTrigger>
  <PopoverContent>
    Content
  </PopoverContent>
</Popover>
```

`PopoverTrigger` accepts `as` to render any component. Pass `as={Button}` for a styled trigger, or omit for a plain `<button>`.

## Header and description [#header-and-description]

<ComponentPreview name="popover-basic" title="popover-basic.tsx" src="examples/popover-basic.tsx">
<PopoverBasic />
</ComponentPreview>

`PopoverHeader`, `PopoverTitle`, and `PopoverDescription` wire `aria-labelledby` and `aria-describedby` onto the content automatically. Use them together so screen readers announce the panel correctly.

## Alignments [#alignments]

<ComponentPreview name="popover-alignments" title="popover-alignments.tsx" src="examples/popover-alignments.tsx">
<PopoverAlignments />
</ComponentPreview>

Pass `align` to control horizontal placement: `start`, `center` (default), or `end`. Pass `side` for `top`, `right`, `bottom` (default), or `left`.

## Form [#form]

<ComponentPreview name="popover-form" title="popover-form.tsx" src="examples/popover-form.tsx">
<PopoverForm />
</ComponentPreview>

Popover panels are not modal. They close on outside click, return focus to the trigger, and do not trap focus. For a focus-trapped experience, use `Dialog`.

## API Reference [#api-reference]

### Popover [#popover]

<PropsTable rows={[{"name":"open","type":"boolean","description":"Controlled open state. When omitted, the popover manages its own state."},{"name":"defaultOpen","type":"boolean","default":"false","description":"Uncontrolled initial open state."},{"name":"onOpenChange","type":"(open: boolean) => void","description":"Called when the popover opens or closes."}]} />

### PopoverTrigger [#popovertrigger]

<PropsTable rows={[{"name":"as","type":"React.ElementType","description":"Renders a different root element or component. Defaults to button."},{"name":"className","type":"string","description":"Additional CSS classes."}]} />

### PopoverHeader [#popoverheader]

<PropsTable rows={[{"name":"className","type":"string","description":"Additional CSS classes. Applies to the wrapper div (flex column, gap-1.5)."}]} />

### PopoverTitle [#popovertitle]

<PropsTable rows={[{"name":"className","type":"string","description":"Additional CSS classes. Renders an h2 with leading-none and font-medium by default."}]} />

### PopoverDescription [#popoverdescription]

<PropsTable rows={[{"name":"className","type":"string","description":"Additional CSS classes. Renders a p with text-muted-foreground and text-sm by default."}]} />

### PopoverContent [#popovercontent]

<PropsTable rows={[{"name":"side","type":"top | right | bottom | left","default":"bottom","description":"Placement relative to the trigger."},{"name":"align","type":"start | center | end","default":"center","description":"Alignment along the cross axis."},{"name":"sideOffset","type":"number","default":"4","description":"Gap between trigger and content in pixels."},{"name":"alignOffset","type":"number","default":"0","description":"Shift along the cross axis in pixels."},{"name":"avoidCollisions","type":"boolean","default":"true","description":"Flip and shift to stay inside the viewport."},{"name":"motion","type":"string","description":"Motion string for the entrance reveal. Pass off to disable."},{"name":"className","type":"string","description":"Additional CSS classes."}]} />

### PopoverClose [#popoverclose]

<PropsTable rows={[{"name":"as","type":"React.ElementType","description":"Renders a different root element or component. Defaults to button."}]} />

## Motion [#motion]

The panel fades and scales in through Frakment's motion engine. Pass `motion` on `PopoverContent`:

```tsx
<PopoverContent motion="200 ease-out">Content</PopoverContent>
```

`motion` accepts `"off"`, `"150"`, `"150 ease-out"`, or `"150 cubic-bezier(0.4, 0, 0.2, 1)"`. The default is a 150ms smooth-out curve. `prefers-reduced-motion` wins and the panel appears instantly.

## Accessibility [#accessibility]

- `PopoverTrigger` sets `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls` on the trigger.
- `PopoverTitle` and `PopoverDescription` wire `aria-labelledby` and `aria-describedby` on the content when present.
- `Escape` closes the popover. Outside click closes the popover.
- Focus moves into the panel on open and returns to the trigger on close. Focus is not trapped.

## Best Practices [#best-practices]

- **Pair a title with a description** when the panel shows form fields or structured content.
- **Use `align="start"`** for panels that should align with the trigger's leading edge, common in toolbars.
- **Keep content short.** Popover is not a modal. Long forms belong in `Dialog`.

## Related Components [#related-components]

- [Button](/docs/components/button): the default trigger
- [Dialog](/docs/components/dialog): modal alternative with focus trap
- [Dropdown Menu](/docs/components/dropdown-menu): menu alternative with keyboard navigation