React Popover Component | Tailgrids Docs

React Popover components display floating content anchored to a trigger element. They are commonly used for contextual information, settings panels, and inline actions that don’t require full navigation.

This Popover component is built with React and styled using Tailwind CSS. It uses Floating UI for positioning and provides accessible focus and keyboard handling.

Installation

The Popover component relies on the @floating-ui/react library.

Install the component using the Tailgrids CLI.

npx @tailgrids/cli add popover

Anatomy

Import the component parts and combine them according to your requirements.

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

export default function PopoverAnatomy() {
  return (
    <Popover>
      <PopoverTrigger />
      <PopoverContent>
        <PopoverHeading />
        <PopoverDescription />
        <PopoverClose />
      </PopoverContent>
    </Popover>
  );
}

Usage

Import the popover components and wrap a trigger with content.

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

export default function PopoverExample() {
  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

Basic popover with heading and description.

With Button

Popover content with action buttons.

With Link

Popover content with a link.

Controlled Open State

Control the open state using React state.

Custom Placement

Change the popover position relative to the trigger.

Note: 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).

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 internally for positioning

PopoverHeading

Registers itself as the aria-labelledby for the popover.

Prop	Type	Description
`children`	`React.ReactNode`	The content of the heading.
`className`	`string`	Optional CSS classes.

PopoverDescription

Registers itself as the aria-describedby for the popover.

Prop	Type	Description
`children`	`React.ReactNode`	The content of the description.
`className`	`string`	Optional CSS classes.

PopoverClose

A convenience button that closes the popover when clicked.

Prop	Type	Description
`children`	`React.ReactNode`	The button label/content.
`className`	`string`	Optional CSS classes.
`onClick`	`(event: React.MouseEvent) => void`	Optional click handler.

Accessibility

Uses aria-labelledby and aria-describedby
Keyboard accessible with Tab, Arrow, Shift+Tab, and Escape
Focus is managed automatically when the popover opens and closes
Triggers expose data-state="open" | "closed"
Works with screen readers and assistive technologies
Supports modal focus trapping when enabled

Popover

CLI

Manual

On this page