Skip to content
CFA Design System

Popover

ReactProps
Github icon-storybook-square Storybook Markdown Copy for LLM

The Popover component provides a way to display content in a floating panel that is anchored to a trigger element.

Import

import { Popover } from "@cfa/react-core";

Live Editor

Guidelines

When to use

  • Popover is for secondary information or controls people open from an anchored trigger.

Do

  • Close on action selection when the popover lists actions or links.
  • When edits are not committed live, include Apply and Cancel in the footer. Close on Apply, not on outside click during edit.

Avoid

  • Putting long forms or critical actions in a Popover. Use Modal.
  • Opening a Popover automatically on page load. Popovers are opt-in.
  • Using Popover for a list of menu actions. Use Menu.
  • Using Popover for a brief, non-interactive hint on hover or focus. Use Tooltip.

Examples

Default Popover

A basic example of the Popover component with a trigger and a panel.

Hover Root

Use Popover.HoverRoot to open a non-modal popover on hover, keyboard focus, or long press. Unlike Tooltip, hover popovers can include interactive content such as links and buttons.

Previews appear after a warmup delay. Once a preview is displayed, other previews display immediately. If the user waits for the cooldown period before hovering another element, the warmup timer restarts. When a preview is open, Tab moves focus into the popover so users can interact with its contents. Press Escape to close the preview and return focus to the trigger.

Use a focusable trigger such as Link or Button. Pass inline on Link when the trigger sits in paragraph text.

Custom Trigger

Using a custom trigger element wrapped in a Pressable component.

Placement

You can control the position of the popover relative to its trigger using the placement prop. The default placement is bottom.

Composition

The Popover component offers two different ways to use it. The simplified Popover.Panel approach (recommended) or the more granular approach using Popover.Wrapper and Popover.Dialog.

For most use cases, we recommend using Popover.Panel. It combines the Wrapper and Dialog components into a single, convenient component.

Alternative: Wrapper & Dialog

For advanced use cases where you need more control over the structure, you can use the Wrapper and Dialog components directly. However, this is generally not necessary and adds complexity.

Events

The Popover component provides an onOpenChange event that allows you to track and control when the popover opens or closes.