Popover | Tailgrids Docs

A floating panel that opens on click. Includes support for headings, descriptions, keyboard focus, arrow positioning, and controlled or uncontrolled behavior.

Installation

Usage

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeading,
  PopoverDescription,
  PopoverClose
} from "@/registry/core/popover";

export default function Example() {
  return (
    <Popover>
      <PopoverTrigger>Open Popover</PopoverTrigger>

      <PopoverContent>
        <PopoverHeading>Popover Title</PopoverHeading>
        <PopoverDescription>
          This is a short description inside the popover.
        </PopoverDescription>

        <PopoverClose className="mt-4 text-sm underline">Close</PopoverClose>
      </PopoverContent>
    </Popover>
  );
}

Examples

Default

<Popover>
  <PopoverTrigger>Options</PopoverTrigger>
  <PopoverContent>
    <PopoverHeading>Settings</PopoverHeading>
    <PopoverDescription>Manage only the settings you need.</PopoverDescription>
  </PopoverContent>
</Popover>

With Close Button

<Popover>
  <PopoverTrigger>Details</PopoverTrigger>
  <PopoverContent>
    <PopoverHeading>Profile</PopoverHeading>
    <p className="text-sm">Edit your personal information.</p>

    <PopoverClose className="mt-4 text-sm underline">Close</PopoverClose>
  </PopoverContent>
</Popover>

Controlled Open State

const [open, setOpen] = useState(false);

<Popover open={open} onOpenChange={setOpen}>
  <PopoverTrigger>Toggle</PopoverTrigger>
  <PopoverContent>
    <p>This popover is fully controlled.</p>
  </PopoverContent>
</Popover>;

Custom Placement

<Popover placement="right-start">
  <PopoverTrigger>Right Popover</PopoverTrigger>
  <PopoverContent>Content positioned on the right.</PopoverContent>
</Popover>

API Reference

Prop	Type	Default	Description
`initialOpen`	`boolean`	`false`	Initial uncontrolled open state
`open`	`boolean`	–	Controlled open state
`onOpenChange`	`(open: boolean) => void`	–	Called when open state changes
`placement`	`Placement` (`@floating-ui`)	`"bottom"`	Position of popover relative to trigger
`modal`	`boolean`	`false`	Trap focus while open

PopoverTrigger

Wraps the clickable element that toggles the popover.

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Use any element as the trigger

PopoverContent

Floating panel element that contains the popover UI.

Prop	Type	Description
`style`	`React.CSSProperties`	Inline style merged with floating-ui positioning styles
`ref`	`React.Ref<HTMLDivElement>`	Used by Floating UI to position content

PopoverHeading

Registers itself as the aria-labelledby for the popover.
Automatically binds/unbinds when mounted/unmounted.

PopoverDescription

Registers itself as aria-describedby for the popover.

PopoverClose

A convenience button that closes the popover when clicked.

Accessibility

Fully accessible using:
- FloatingFocusManager for focus handling
- aria-labelledby and aria-describedby
- Arrow key and tab navigation
Triggers expose data-state="open" | "closed"
Works with screen readers and assistive tech
Supports modal focus-trapping

Notes

Uses FloatingArrow for accurate arrow positioning
Supports both controlled and uncontrolled states
Automatically flips, shifts, and offsets using Floating UI middleware
asChild allows integrating with custom buttons (Radix-style)

CLI

Manual

On this page