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.


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.

Usage

With Arrow

Colors

Placements

Offset

Controlled

Title Props

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.
  • trigger: The popover trigger slot, it has small styles to ensure the trigger works correctly.
  • backdrop: The backdrop slot, it contains the backdrop styles.
  • arrow: The arrow slot, it wraps the popover arrow, the placement of the arrow is based on the popover placement, e.g. data-[placement=top]:....

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

Popover Props

AttributeTypeDescriptionDefault
children*ReactNode[]The content of the popover. It's usually the PopoverTrigger and PopoverContent.-
sizesm | md | lgThe popover content font size.md
colordefault | primary | secondary | success | warning | dangerThe popover color theme.default
radiusnone | sm | md | lg | fullThe popover border radius.lg
shadownone | sm | md | lgThe popover shadow.lg
backdroptransparent | opaque | blurThe popover backdrop type.transparent
placementPopoverPlacementThe placement of the popover relative to its trigger reference.bottom
stateOverlayTriggerStateThe controlled state of the popover. See Overlay States-
isOpenbooleanWhether the popover is open by default (controlled).-
defaultOpenbooleanWhether the popover is open by default (uncontrolled).-
offset(px)numberThe distance or margin between the reference and popper. It is used internally to create an offset modifier.7
containerPadding(px)numberThe placement padding that should be applied between the element and its surrounding container.12
crossOffset(px)numberThe additional offset applied along the cross axis between the element and its anchor element.0
triggerTypedialog | menu | listbox | tree | grid;Type of popover that is opened by the trigger.dialog
showArrowbooleanWhether the popover should have an arrow.false
shouldFlipbooleanWhether the popover should change its placement and flip when it's about to overflow its boundary area.true
triggerScaleOnOpenbooleanWhether the trigger should scale down when the popover is open.true
shouldBlockScrollbooleanWhether to block scrolling outside the popover.false
isKeyboardDismissDisabledbooleanWhether pressing the escape key to close the popover should be disabled.false
shouldCloseOnBlurbooleanWhether the popover should close when focus is lost or moves outside it.false
motionPropsMotionPropsThe props to modify the framer motion animation. Use the variants API to create your own animation.
portalContainerHTMLElementThe container element in which the overlay portal will be placed.document.body
triggerRefRefObject<HTMLElement>The ref for the element which the popover positions itself with respect to.-
scrollRefRefObject<HTMLElement>A ref for the scrollable region within the popover.overlayRef
disableAnimationbooleanWhether the popover is animated.false
classNamesRecord<"base"| "trigger"| "backdrop"| "arrow", string>Allows to set custom class names for the popover slots.-

Popover Events

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

PopoverTrigger 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.-

PopoverContent Props

AttributeTypeDescriptionDefault
childrenReactNodeThe content that is displayed when the trigger is pressed.-

Popover types

Popover Placement

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/