Popover

Popover is a non-modal dialog that floats around its disclosure. It's commonly used for displaying additional rich content on top of something. Popover implementation is based on @react-aria/overlays.

import { Popover } from '@nextui-org/react';

Anatomy

  • Popover: The wrapper that provides props, state, and context to its children.
  • Popover.Trigger: Used to wrap the reference (or trigger) element.
  • Popover.Content: The content that is displayed when the trigger is clicked.

Default

Shows how to build a typical popover overlay that is positioned relative to a trigger button.

The Popover can be closed by clicking or interacting outside the popover, or by pressing the Escape key. When the popover is closed, focus is restored back to its trigger button.

Placements

Positions the popover relative to the trigger button. The position is automatically adjusted when the Popover is likely to be offscreen or when the window is resized.

The Popover is automatically hidden when the user scroll the page.

Controlled vs Uncontrolled

The defaultOpen prop can be used to set the default state (uncontrolled). Alternatively, the isOpen prop can be used to make the selected state controlled.

Note: See React's documentation on uncontrolled components for more info.

Custom Content

The Popover.Content can be used to render any component you want. Ensure the children passed to Popover.Trigger is focusable. Users can tab to it using their keyboard, and it can take a ref. It is critical for accessiblity.

A11y: When Popover opens, focus is sent to PopoverContent. When it closes, focus is returned to the trigger.

Disable animation

Disables the animation of the popover when it is opened or closed.

APIs

Popover Props

AttributeTypeDescriptionDefault
childrenReactNodeThe content of the popover. It's usually the Popover.Trigger and Popover.Content.-
placementPopoverPlacementThe placement of the popover relative to its trigger reference.bottom
triggerTypePopoverPlacementType of overlay that is opened by the trigger.dialog
shouldFlipbooleanWhether the popover should change its placement and flip when it's about to overflow its boundary area.true
offset(px)numberThe distance or margin between the reference and popper. It is used internally to create an offset modifier.12
isOpenbooleanWhether the overlay is open by default (controlled).-
defaultOpenbooleanWhether the overlay is open by default (uncontrolled).-
isDismissablebooleanWhether to close the overlay when the user interacts outside it.true
isKeyboardDismissDisabledbooleanWhether pressing the escape key to close the overlay should be disabled.false
shouldCloseOnBlurbooleanWhether the overlay should close when focus is lost or moves outside it.false
disableAnimationbooleanWhether the popover is animated.false

Popover Events

AttributeTypeDescriptionDefault
onOpenChange(isOpen: boolean) => voidHandler that is called when the overlay's open state changes.-
onClose() => voidHandler that is called when the overlay should close.-
shouldCloseOnInteractOutside(e: HTMLElement) => voidWhen user interacts with the argument element outside of the overlay ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the overlay. By default, onClose will always be called on interaction outside the overlay ref.-

Popover.Trigger Props

AttributeTypeDescriptionDefault
children*ReactNodeThe popover trigger component, ensure the children passed is focusable. Users can tab to it using their keyboard, and it can take a ref. It is critical for accessiblity.-

Popover.Content Props

AttributeTypeDescriptionDefault
childrenReactNodeThe content that is displayed when the trigger is clicked.-
cssStitches.CSSOverride Default CSS style.-
askeyof JSX.IntrinsicElementsChanges which tag component outputs.div
...HTMLDivElementNative element props.-

Popover types

Popover Placement

type PopoverPlacement =
  | 'bottom'
  | 'bottom-left'
  | 'bottom-right'
  | 'top'
  | 'top-left'
  | 'top-right'
  | 'left'
  | 'left-top'
  | 'left-bottom'
  | 'right'
  | 'right-top'
  | 'right-bottom';

Trigger Type

type TriggerType = 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid';
gradient blue backgroundgradient violet background