# Popover

> An anchored frosted panel for arbitrary content: a short form, a set of options, a details block.

Category: Overlays. Docs page: https://rime.mjsons.net/components/popover

## Installation

```bash
npx shadcn@latest add KezLahd/rime/popover
```

Popover opens a panel against its trigger, in the same frosted glass as Select and Menu. The trigger is any button you pass; Popover adds aria-expanded, aria-controls and the click handler. It flips above when there is no room below and follows scroll and resize.

Focus moves to the first focusable element inside (or the panel) but is not trapped. Esc closes it and returns focus to the trigger; a press outside closes it too. Open state is uncontrolled by default, or controlled with open and onOpenChange.

inline renders the open panel in the page flow: no portal, scrim, focus trap, scroll lock or outside-click listener. It exists for docs, previews and static mock-ups; never ship it as the live overlay.

## Usage

```tsx
import { Button, Popover } from "@/components/ui";

<Popover label="Canvas dimensions" trigger={<Button variant="secondary">Dimensions</Button>}>
  …fields…
</Popover>
```

## Props: Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` (required) | `ReactElement<TriggerProps>` |  | The button that opens it. Gets aria-expanded, aria-controls and the click handler. |
| `children` (required) | `ReactNode` |  | The panel's content: a short form, a set of filters, a details block. |
| `label` | `string` |  | The panel's accessible name ("Edit dimensions"). Use it when the content has no heading. |
| `open` | `boolean` |  | Controlled open state. Leave unset for uncontrolled. |
| `defaultOpen` | `boolean` |  |  |
| `onOpenChange` | `(open: boolean) => void` |  |  |
| `side` | `FloatSide` | `"bottom"` | Preferred side; flips when there is no room. |
| `align` | `FloatAlign` | `"start"` |  |
| `width` | `number` |  | Panel width in px. Defaults to the content's width (min 220px). |
| `inline` | `boolean` |  | Render the open panel in the page flow under the trigger: not portalled, no outside-click or Esc handling. For docs, previews and static mock-ups. |
| `className` | `string` |  |  |

## Examples

### Open

The panel under its trigger, drawn inline.

```tsx
<Popover inline label="Canvas dimensions" width={260} trigger={<Button variant="secondary">Dimensions</Button>}>
  <Field label="Width"><TextInput size="sm" defaultValue="1280" trailing="px" /></Field>
  <Field label="Height"><TextInput size="sm" defaultValue="720" trailing="px" /></Field>
</Popover>
```

### From its trigger

Press the button. Esc or a press outside closes it.

```tsx
<Popover label="Canvas dimensions" width={260} trigger={<Button variant="secondary">Dimensions</Button>}>
  …
</Popover>
```

## Theme tokens

Per-component tokens. Undeclared by default: the default below is the fallback the CSS uses. Set any of them at :root or on a wrapper to restyle every instance.

| Token | Default |
| --- | --- |
| `--popover-content-pad` | `calc(16px * var(--density))` |
| `--popover-max-width` | `380px` |
| `--popover-min-width` | `220px` |
| `--popover-radius` | `var(--r-lg)` |

System tokens it reads: `--border-w`, `--density`, `--dur`, `--dur-slow`, `--ease-out`, `--focus-ring`, `--ink-body`, `--popover-blur`, `--popover-border`, `--popover-shadow`, `--popover-surface`, `--r-lg`, `--text-small`, `--z-popover`.

## Accessibility

- The panel is role="dialog" named by label (or by a heading you give it); the trigger carries aria-expanded and aria-controls.
- Focus moves into the panel on open and back to the trigger on Esc. It is non-modal: Tab can leave it.
- Do not put the only route to an action in a popover that opens on hover; Popover opens on press only.

## Do

- Keep it to one small task: a few fields, a choice, a summary.
- Give it a label when the content has no heading.

## Don't

- Don't use it for a list of actions; that is Menu.
- Don't put a long form in it; use Sheet or Modal.

Related: https://rime.mjsons.net/components/hover-card, https://rime.mjsons.net/components/menu, https://rime.mjsons.net/components/tooltip