Popover React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import Popover from @/components/ui/popover.

import { ChevronDown } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Popover, PopoverClose } from "@/components/ui/popover"

export function PriceFilter({ onApply, onReset }: { onApply: () => void; onReset: () => void }) {
  return (
    <Popover
      trigger={
        <Button variant="soft" rightIcon={<ChevronDown />}>
          Price
        </Button>
      }
      title="Price"
      description="Pick a range or type your own."
      align="start"
      arrow
      sheetTitle="Price filter"
      footer={
        <>
          <Button variant="ghost" size="sm" onClick={onReset}>
            Reset
          </Button>
          <PopoverClose asChild>
            <Button size="sm" onClick={onApply}>
              Apply
            </Button>
          </PopoverClose>
        </>
      }
    >
      <p className="text-muted-foreground">Between $500 and $1,500</p>
    </Popover>
  )
}

Props

• defaultOpendefault false
  boolean

  Starts open (uncontrolled). Pass open and onOpenChange instead to control it.

• open
  boolean

  Controlled open state. The root keeps it across the 768px breakpoint, so turning a tablet never closes the popover.

• onOpenChange
  (open: boolean) => void

  Called when it opens or closes: the trigger, Escape, a click outside, focus leaving it, the shortcut or a close button.

• titledefault ""
  ReactNode

  An optional heading at the top, 15px semibold; it names the panel for screen readers. The demo shows its sample while this is empty.

• descriptiondefault ""
  ReactNode

  A quieter line under the title, wired to aria-describedby.

• closeLabeldefault "Close"
  string

  aria-label of the close button, e.g. a translated “Close” for another language.

• sheetTitledefault "Details"
  string

  The name screen readers hear while there is no title: the bottom sheet's hidden title on phones and the panel's aria-label on desktop.

• trigger
  ReactNode

  The element that opens it, rendered with asChild: a single element that takes a ref, like a Button. It gets aria-expanded, aria-controls, data-state and, with a shortcut, aria-keyshortcuts.

• children
  ReactNode

  The body, 14px text. It scrolls when the panel would be taller than the space on screen.

• footer
  ReactNode

  Actions under the body, primary last: a right-aligned row of size="sm" buttons in the panel, stacked full width with the primary on top in the sheet (buttons grow to 48px there on their own).

• sidedefault "bottom"
  "top" | "right" | "bottom" | "left"

  The side of the trigger it opens on. It flips to the opposite side when there is no room.

• aligndefault "center"
  "start" | "center" | "end"

  How it lines up with the trigger along that side: its start edge, its center or its end edge.

• sideOffsetdefault 8
  number

  Gap in px between the trigger and the panel (the arrow adds its own 8px).

• alignOffsetdefault 0
  number

  Shifts the panel along the trigger's edge, in px, from where align puts it.

• sizedefault "md"
  "sm" | "md" | "lg" | "auto"

  Width 256 / 288 / 384px, or auto to fit the content (at least 192px). Always at most the screen width minus 24px.

• paddingdefault "md"
  "none" | "sm" | "md" | "lg"

  Space inside the panel: 0 / 12 / 16 / 20px. none is for full-bleed lists and media. The sheet on phones keeps its own 20px sides (check usePopover().sheet to lay out rows for it).

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner radius 0 / 12 / 16 / 24px (full is 24px, like every floating surface). The sheet keeps its 28px top corners.

• arrowdefault false
  boolean

  A 16 x 8 arrow with a rounded tip pointing at the trigger, in the panel's color with the same hairline. It keeps clear of the rounded corners and hides when it cannot point at the trigger.

• showClosedefault false
  boolean

  A round X in the top corner, centered on the title's line. Escape and a click outside always close it too.

• modaldefault false
  boolean

  Traps focus inside, blocks clicks on the page and locks its scroll until the popover closes. For a confirm or a form that must be finished or cancelled.

• responsivedefault true
  boolean

  Below 768px it opens as the drawer's bottom sheet: handle, drag to dismiss, pinned header and footer, safe-area padding. false keeps the floating panel on phones (an autocomplete under a field).

• shortcutdefault ""
  string

  A key combo in mod+k notation (⌘ on Apple devices, Ctrl elsewhere) that toggles it from anywhere on the page; the trigger gets aria-keyshortcuts. Empty binds nothing.

• onOpenAutoFocus
  (event: Event) => void

  Runs when it opens, before focus moves in. Call event.preventDefault() to keep focus where it is (an anchored suggestion list under a field).

• container
  HTMLElement | null

  Portal target, document.body by default. The sheet renders there too.

• classNames
  Partial<Record<"content" | "viewport" | "header" | "title" | "description" | "body" | "footer" | "close" | "arrow", string>>

  Extra classes for the inner parts: the panel, its scrolling viewport (which holds the padding), the header, title, description, body, footer, the close button and the arrow. The same keys style the sheet's parts on phones.

• className
  string

  Extra classes for the panel (popover-content), merged last, e.g. w-(--radix-popover-trigger-width) to match an anchor. A width here never narrows the sheet.

Parts

FAQ

Used in

More React overlay components