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.

Storybook @nextui-org/popover React Aria Source Styles source

Installation

npx nextui-cli@latest add popover

The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

NextUI exports 3 popover-related components:

Popover: The main component to display a popover.
PopoverTrigger: The component that triggers the popover.
PopoverContent: The component that contains the popover content.

To be sure that the popover exposes the correct title to assistive technologies, you should use the titleProps prop on the PopoverContent component. To use this prop, you must pass a function as a child.

With Form

The Popover handles the focus within the popover content. It means that you can use the popover with form elements without any problem. the focus returns to the trigger when the popover closes.

Note: You can add the autoFocus prop to the first Input component to focus it when the popover opens.

Backdrop

The Popover component has a backdrop prop to show a backdrop behind the popover. The backdrop can be either transparent, opaque or blur. The default value is transparent.

Custom Motion

Popover offers a motionProps property to customize the enter / exit animation.

Learn more about Framer motion variants here.

Custom Trigger

Slots

base: The main popover slot, it wraps the popover content and contains the arrow as a pseudo-element (::before).
trigger: The popover trigger slot, it has small styles to ensure the trigger works correctly.
backdrop: The backdrop slot, it contains the backdrop styles.
content: The content slot, it contains the popover content.

Custom Styles

You can customize the Popover component by passing custom Tailwind CSS classes to the component slots.

Data Attributes

Popover has the following attributes on the PopoverContent element:

data-open: When the popover is open. Based on popover state.
data-placement: The placement of the popover. Based on placement prop. The arrow element is positioned based on this attribute.
data-focus: When the popover is being focused. Based on useFocusRing.
data-focus-visible: When the popover is being focused with the keyboard. Based on useFocusRing.

Accessibility

The trigger and popover are automatically associated semantically via ARIA.
Content outside the popover is hidden from assistive technologies while it is open.
The popover closes when interacting outside, or pressing the Escape key.
Focus is moved into the popover on mount, and restored to the trigger element on unmount.
The popover is positioned relative to the trigger element, and automatically flips and adjusts to avoid overlapping with the edge of the browser window.
Scrolling is prevented outside the popover to avoid unintentionally repositioning or closing it.

API

Prop	Type	Default
`children*`	`ReactNode[]`
`size`	`sm \| md \| lg`	`"md"`
`color`	`default \| primary \| secondary \| success \| warning \| danger`	`"default"`
`radius`	`none \| sm \| md \| lg \| full`	`"lg"`
`shadow`	`none \| sm \| md \| lg`	`"lg"`
`backdrop`	`transparent \| opaque \| blur`	`"transparent"`
`placement`	`PopoverPlacement`	`"bottom"`
`state`	`OverlayTriggerState`
`isOpen`	`boolean`
`defaultOpen`	`boolean`
`offset`	`number`	`"7"`
`containerPadding`	`number`	`"12"`
`crossOffset`	`number`	`"0"`
`triggerType`	`dialog \| menu \| listbox \| tree \| grid`	`"dialog"`
`showArrow`	`boolean`	`false`
`shouldFlip`	`boolean`	`true`
`triggerScaleOnOpen`	`boolean`	`true`
`shouldBlockScroll`	`boolean`	`true`
`shouldCloseOnScroll`	`boolean`	`false`
`isKeyboardDismissDisabled`	`boolean`	`false`
`shouldCloseOnBlur`	`boolean`	`false`
`motionProps`	`MotionProps`
`portalContainer`	`HTMLElement`	`"document.body"`
`disableAnimation`	`boolean`	`false`
`classNames`	`Partial<Record<'base' \| 'trigger' \| 'backdrop' \| 'content', string>>`

Prop	Type	Default
`onOpenChange`	`(isOpen: boolean) => void`
`shouldCloseOnInteractOutside`	`(e: HTMLElement) => void`
`onClose`	`() => void`

PopoverTrigger Props

Prop	Type	Default
`children*`	`ReactNode`

PopoverContent Props

Prop	Type	Default
`children`	`ReactNode`

type PopoverPlacement =
  | "top"
  | "bottom"
  | "right"
  | "left"
  | "top-start"
  | "top-end"
  | "bottom-start"
  | "bottom-end"
  | "left-start"
  | "left-end"
  | "right-start"
  | "right-end";

Motion Props

export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/

Popover

Installation

Import

Usage

With Arrow

Colors

Placements

Offset

Controlled

Title Props