Popover

A floating panel that opens from a button and can hold any content.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"

const styles = stylex.create({
  content: { width: "20rem" },
  label: { flexGrow: 0, flexShrink: 0, flexBasis: "6rem" },
})

const dimensions = [
  { id: "popover-demo-width", label: "Width", value: "100%" },
  { id: "popover-demo-max-width", label: "Max. width", value: "640px" },
  { id: "popover-demo-height", label: "Height", value: "auto" },
  { id: "popover-demo-max-height", label: "Max. height", value: "none" },
]

export default function PopoverDemo() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>Open popover</PopoverTrigger>
      <PopoverContent xstyle={styles.content}>
        <PopoverHeader>
          <PopoverTitle>Dimensions</PopoverTitle>
          <PopoverDescription>Set the size of the selected frame.</PopoverDescription>
        </PopoverHeader>
        <FieldGroup gap={2}>
          {dimensions.map((dimension) => (
            <Field key={dimension.id} orientation="horizontal">
              <FieldLabel xstyle={styles.label}>{dimension.label}</FieldLabel>
              <Input id={dimension.id} defaultValue={dimension.value} />
            </Field>
          ))}
        </FieldGroup>
      </PopoverContent>
    </Popover>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/popover

Needs the arene setup first.

Usage

import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"
<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>Open</PopoverTrigger>
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Dimensions</PopoverTitle>
      <PopoverDescription>Set the size of the selected frame.</PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>

Composition

Popover
├── PopoverTrigger
└── PopoverContent          portal + positioner + popup
    ├── PopoverHeader
    │   ├── PopoverTitle
    │   └── PopoverDescription
    └── PopoverClose

PopoverTrigger renders a <button>. Pass render to use another element as the trigger, such as a Button variant.

The popup is a column with a 0.625rem gap, so PopoverHeader and whatever follows it need no margins of their own.

Basic

PopoverHeader stacks PopoverTitle over PopoverDescription. Base UI wires both to the popup's aria-labelledby and aria-describedby.

import { Button } from "@/components/ui/button"
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"

export default function PopoverBasic() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>Open popover</PopoverTrigger>
      <PopoverContent align="start">
        <PopoverHeader>
          <PopoverTitle>Dimensions</PopoverTitle>
          <PopoverDescription>Set the size of the selected frame.</PopoverDescription>
        </PopoverHeader>
      </PopoverContent>
    </Popover>
  )
}

Align

Use align on PopoverContent to slide the popup along the trigger's edge, and side to pick which edge it opens from. Base UI flips the side when there is no room.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"
import { HStack } from "@/components/ui/stack"

const styles = stylex.create({
  content: { width: "10rem" },
})

const alignments = ["start", "center", "end"] as const

export default function PopoverAlignments() {
  return (
    <HStack gap={6}>
      {alignments.map((align) => (
        <Popover key={align}>
          <PopoverTrigger render={<Button variant="outline" size="sm" />}>{align}</PopoverTrigger>
          <PopoverContent align={align} xstyle={styles.content}>
            Aligned to {align}
          </PopoverContent>
        </Popover>
      ))}
    </HStack>
  )
}

With form

Put controls straight in the popup. PopoverClose is a button that closes it, so a cancel and a confirm both go through the same part.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import {
  Popover,
  PopoverClose,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"
import { HStack } from "@/components/ui/stack"

const styles = stylex.create({
  label: { flexGrow: 0, flexShrink: 0, flexBasis: "4rem" },
})

export default function PopoverForm() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>Open popover</PopoverTrigger>
      <PopoverContent align="start">
        <PopoverHeader>
          <PopoverTitle>Dimensions</PopoverTitle>
          <PopoverDescription>Set the size of the selected frame.</PopoverDescription>
        </PopoverHeader>
        <FieldGroup gap={2}>
          <Field orientation="horizontal">
            <FieldLabel xstyle={styles.label}>Width</FieldLabel>
            <Input id="popover-form-width" defaultValue="100%" />
          </Field>
          <Field orientation="horizontal">
            <FieldLabel xstyle={styles.label}>Height</FieldLabel>
            <Input id="popover-form-height" defaultValue="auto" />
          </Field>
          <HStack gap={2} justify="end">
            <PopoverClose render={<Button variant="ghost" size="sm" />}>Cancel</PopoverClose>
            <PopoverClose render={<Button size="sm" />}>Save</PopoverClose>
          </HStack>
        </FieldGroup>
      </PopoverContent>
    </Popover>
  )
}

A popover is not modal by default. The page keeps scrolling and a click outside closes it. Pass modal to Popover to lock the page instead, and render a PopoverClose inside the popup. Base UI only traps focus when it finds one, so without it a keyboard user can tab back out of a locked page.

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Popover part of the same name and accepts its props. See the Base UI reference for the full list. Each styled part also takes xstyle and className.

Popover

PropTypeDefault
openboolean—
defaultOpenbooleanfalse
onOpenChange(open: boolean, details) => void—
modalboolean | "trap-focus"false
handlePopoverHandle—

PopoverTrigger

PropTypeDefault
openOnHoverbooleanfalse
delaynumber300
closeDelaynumber0
payloadPayload—

delay and closeDelay do nothing without openOnHover.

PopoverContent

PropTypeDefault
side"top" | "bottom" | "left" | "right""bottom"
sideOffsetnumber4
align"start" | "center" | "end""center"
alignOffsetnumber0

The popup is 18rem wide and clamped to --available-width, so it narrows rather than overflowing a phone-width viewport. Change the width through xstyle.

Data attributes

AttributeOnEffect
data-slot="popover-content"the popupPopup surface
data-side, data-alignthe popupWhich way it slides in from
data-starting-style, data-ending-stylethe popupBase UI writes them while the popup animates
data-open, data-closedbothBase UI writes them on the trigger and the popup