---
title: "Popover"
description: "A small panel anchored to the control that opened it, floated in a portal and dismissed by leaving it, built as a thin themed wrapper over Base UI Popover."
url: "https://opsinjs.pensievelabs.org/docs/components/popover"
source: "https://opsinjs.pensievelabs.org/docs/components/popover.md"
section: "Components"
status: "shipped"
kind: "component"
category: "overlay"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["anchored panel", "flyout"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="popover"
  status="shipped"
  questions="[
  &#x22;Nobody has heard a popover in a screen reader, so whether a non-modal dialog over a live page reads usefully is open.&#x22;,
  &#x22;No contrast pair has been measured: the card panel, its hairline, the arrow and the trigger are argued from the roles rather than checked.&#x22;,
  &#x22;Under forced-colors: active the shadow drops and the arrow takes the platform's own pair, and no high-contrast reader has seen it.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="popover" unbuilt="false" importPath="@/components/ui/popover" dependencies="[&#x22;@base-ui/react&#x22;]" />

```tsx
import { Popover } from "@/components/ui/popover"
```

```tsx
<Popover title="How readings are grouped" trigger="Why two lists?">
  <p>
    Entries you add yourself sit in one list, and entries from a connected
    device sit in another, so you can always tell which is which.
  </p>
</Popover>
```

## Examples [#examples]

<ComponentPreview name="popover" />

### Anchored to a button [#anchored-to-a-button]

A short note anchored to a button, left uncontrolled. Escape or an outside press
closes it and returns focus.

<ComponentPreview name="popover-anchored-to-a-button" kind="example" align="start" />

### With a form fragment [#with-a-form-fragment]

A labelled input and a save button. `open` and `onOpenChange` take the state over,
since a control inside closes it.

<ComponentPreview name="popover-with-a-form-fragment" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A short aside anchored to a control, such as a note explaining a label.&#x22;,
  &#x22;A couple of options or a small form fragment, such as renaming a list.&#x22;,
  &#x22;Anywhere dismissing without acting is a valid outcome, because the page behind stays live.&#x22;,
]"
  avoid="[
  { case: &#x22;The reader must answer before they carry on, so dismissing would leave the product guessing.&#x22;, instead: &#x22;dialog&#x22; },
  { case: &#x22;The content is a large form, or needs its own scroll and a docked layout.&#x22;, instead: &#x22;sheet&#x22; },
  { case: &#x22;You only want a short passive label, nothing to open or dismiss.&#x22;, instead: &#x22;term&#x22; },
]"
/>

## Accessibility [#accessibility]

The panel is `role="dialog"`, named by `aria-labelledby`, and a missing title warns.
Base UI moves focus into the panel on open and back to the trigger on close. The arrow
is `aria-hidden`. The panel unfolds from its trigger and comes into focus as it
settles, and under `prefers-reduced-motion` only a short opacity crossfade remains. The
component uses only neutral chrome, the `overlay` shadow token and the `body` and
`headline` steps, with no status colour, literal, ramp step or `px` size. The trigger's
hit area was floored on height alone, so an icon-only trigger could clear the AA 24px
minimum while still missing the house width floor. The audit added a matching `min-w`
at `--opsin-target-minimum`, following the `icon-button` pattern, so the width is
floored too.

**Residual items.**

* The wrapper takes no `aria-label` prop, so an icon-only trigger needs a name from the
  caller's trigger node. Every shipped trigger already uses named text.
* Contrast pairs remain unmeasured, below.

<KeyboardTable
  name="popover"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus to the trigger&#x22;,
    notes: &#x22;One tab stop; the panel joins the tab order only when open.&#x22;,
  },
  {
    keys: &#x22;Enter, Space&#x22;,
    action: &#x22;Opens the panel from the trigger&#x22;,
    notes: &#x22;Focus moves onto its first focusable content.&#x22;,
  },
  {
    keys: &#x22;Escape&#x22;,
    action: &#x22;Closes the panel&#x22;,
    notes: &#x22;Focus returns to the trigger.&#x22;,
  },
  {
    keys: &#x22;Tab, Shift + Tab&#x22;,
    action: &#x22;Moves through the focusable content in the panel&#x22;,
    notes: &#x22;Focus is not trapped; past the last control it leaves the panel.&#x22;,
  },
]"
/>

<ContrastReport component="popover" />

## Props interface [#props-interface]

<PropsTable name="PopoverProps" />

`trigger` is the button's visible content; a button here would nest inside another.
`side` defaults to `bottom`, a preference the primitive overrides on collision.
`className` merges onto the panel and must resolve neither colour axis.
