Components
Popover
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.
Usage
pnpm dlx shadcn@latest add @opsinjs/popover
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Popover } from "@/components/ui/popover"<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
popover · base base · style base-lyraOpen under the product themeAnchored to a button
A short note anchored to a button, left uncontrolled. Escape or an outside press closes it and returns focus.
popover-anchored-to-a-button · base base · style base-lyraOpen under the product theme"use client"
import { Popover } from "@/components/ui/popover"
export default function PopoverAnchoredToAButton() {
return (
<div className="flex w-full max-w-sm justify-start">
<Popover title="How readings are grouped" trigger="Why two lists?">
<p className="m-0 [color:var(--foreground)]">
Entries you add yourself sit in one list, and entries brought in from a
connected device sit in another, so you can always tell which is which.
You can move an entry between them at any time.
</p>
</Popover>
</div>
)
}With a form fragment
A labelled input and a save button. open and onOpenChange take the state over,
since a control inside closes it.
popover-with-a-form-fragment · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { Popover } from "@/components/ui/popover"
const INPUT =
"w-full rounded-opsin-md border border-border bg-background " +
"px-opsin-3 py-opsin-2 min-h-(--opsin-target-minimum,2.75rem) " +
"text-opsin-body [color:var(--foreground)] " +
"focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)] focus-visible:outline-ring"
const SAVE =
"inline-flex items-center justify-center rounded-opsin-md border border-border bg-muted " +
"px-opsin-3 py-opsin-2 min-h-(--opsin-target-minimum,2.75rem) " +
"text-opsin-body [color:var(--foreground)] cursor-pointer " +
"transition-colors duration-(--opsin-duration-fast) ease-opsin-standard hover:bg-state-hover " +
"focus-visible:outline-[length:var(--opsin-border-focus,2px)] focus-visible:outline-offset-[var(--opsin-border-focus-offset,2px)] focus-visible:outline-ring"
export default function PopoverWithAFormFragment() {
const [open, setOpen] = useState(false)
return (
<div className="flex w-full max-w-sm justify-start">
<Popover
open={open}
onOpenChange={setOpen}
title="Rename this list"
trigger="Rename"
>
<form
className="flex w-64 max-w-full flex-col gap-opsin-3"
onSubmit={(event) => {
event.preventDefault()
setOpen(false)
}}
>
<label className="flex flex-col gap-opsin-1">
<span className="text-opsin-footnote [color:var(--muted-foreground)]">
List name
</span>
<input
className={INPUT}
type="text"
defaultValue="Morning entries"
autoComplete="off"
/>
</label>
<button type="submit" className={SAVE}>
Save name
</button>
</form>
</Popover>
</div>
)
}When to use it
Use it when
- A short aside anchored to a control, such as a note explaining a label.
- A couple of options or a small form fragment, such as renaming a list.
- Anywhere dismissing without acting is a valid outcome, because the page behind stays live.
Do not use it when
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-labelprop, 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.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus to the trigger | One tab stop; the panel joins the tab order only when open. |
| Enter, Space | Opens the panel from the trigger | Focus moves onto its first focusable content. |
| Escape | Closes the panel | Focus returns to the trigger. |
| Tab, Shift+Tab | Moves through the focusable content in the panel | Focus is not trapped; past the last control it leaves the panel. |
Contrast: 52 measured token pairs, 16 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| body text on the canvas material | light | 104.7 | 17.96:1 | Pass |
| body text on the canvas material | dark | -100.5 | 18.00:1 | Pass |
| body text on the inset material | light | 98.1 | 16.32:1 | Pass |
| body text on the inset material | dark | -100.1 | 17.18:1 | Pass |
| body text on the card material | light | 104.7 | 17.96:1 | Pass |
| body text on the card material | dark | -99.6 | 16.32:1 | Pass |
| body text on the raised material | light | 104.7 | 17.96:1 | Pass |
| body text on the raised material | dark | -97.5 | 13.77:1 | Pass |
| body text on the sheet material over the darkest backdrop | light | 99.9 | 16.76:1 | Pass |
| body text on the sheet material over the darkest backdrop | dark | -99.7 | 16.47:1 | Pass |
| body text on the sheet material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the sheet material over the lightest backdrop | dark | -80.8 | 6.07:1 | Pass |
| body text on the overlay material over the darkest backdrop | light | 85.9 | 13.48:1 | Pass |
| body text on the overlay material over the darkest backdrop | dark | -99.9 | 16.77:1 | Pass |
| body text on the overlay material over the lightest backdrop | light | 104.7 | 17.96:1 | Pass |
| body text on the overlay material over the lightest backdrop | dark | -54.2 | 2.69:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from PopoverProps in registry/bases/base/popover.tsx.
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.