Popover is a non-modal dialog that floats around a trigger. It is used to display contextual information to the user, and should be paired with a clickable trigger element.

Popover is built on top of the Popper.js library, and composes the Popper component.


  • Popover: The wrapper that provides props, state, and context to its children.
  • PopoverTrigger: Used to wrap the reference (or trigger) element.
  • PopoverContent: The popover itself.
  • PopoverHeader: The header of the popover.
  • PopoverBody: The body of the popover.
  • PopoverArrow: A visual arrow that points to the reference (or trigger).
  • PopoverCloseButton: A button to close the popover.
import {
} from '@nature-ui/core';

Basic Usage#

When using this component, ensure the children passed to PopoverTrigger is focusable. Users can tab to it using their keyboard, and it can take a ref. It is critical for accessiblity.

Editable Example

Rendering the Popover in a Portal#

By default, the Popover doesn't render in a Portal. To make them display in a portal, wrap the PopoverContent in a Portal

You might need to Inspect Element to see this in action. Notice that PopoverContent is rendered as a child of <body>

Editable Example

Focus an element when Popover opens#

By default, focus is to sent to PopoverContent when it opens. Pass the initialFocusRef prop to send focus to a specific element instead.

Editable Example

Trapping Focus within Popover#

If the popover contains a form, you might need to trap focus within the popover and close it when the user fills the form and hits "save".

You can leverage react-focus-lock to trap focus within the PopoverContent.

John Smith
Editable Example

Controlled Usage#

You can control the opening and closing of the popover by passing the isOpen, and onClose props.

Sometimes you might need to set the returnFocusOnClose prop to false to prevent popver from returning focus to PopoverTrigger's children.

Editable Example

Accessing Internal state#

Nature UI provides access to two internal details: isOpen and onClose. Use the render prop pattern to gain access to them.

Editable Example

Customizing the Popover#

Nature UI exports all the components you need to customize the look and feel of the popover. You can change the background, arrow size, box shadow and so on.

Editable Example

Popover Placements#

Since popover is powered by PopperJS, you can change the placement of the popover by passing the placement prop. See the props for the possible placement values.

Even though you specified the placement, Popover will try to reposition itself in the event that available space at the specified placement isn't enough.

Editable Example

Lazily mounting Popover#

By default, the Popover component renders children of PopoverContent to the DOM, meaning that invisible popover contents are still rendered but are hidden by styles.

If you want to defer rendering of popover content until that Popover is opened, you can use the isLazy prop. This is useful if your PopoverContent needs to be extra performant, or make network calls on mount that should only happen when the component is displayed.

Editable Example


When you see the word "trigger", it is referring to the children of PopoverTrigger

Keyboard and Focus#

  • When the popover is opened, focus is moved to clickable elements in PopoverContent component. If the initialFocusRef is set, then focus moves to the element with that ref.
  • If trigger is set to hover:
    • Focusing on or mousing over the trigger will open the popover.
    • Blurring or mousing out of the trigger will close the popover. If you move your mouse into the PopoverContent, it'll remain visible.
  • If trigger is set to click:
    • Clicking the trigger or using the Space or Enter when focus is on the trigger will open the popover.
    • Clicking the trigger again will close the popover.
  • Hitting the Esc key while the popover is open and focus is within the PopoverContent, will close the popover. If you set closeOnEsc to false, it will not close.
  • Clicking outside or blurring out of the PopoverContent closes the popover. If you set closeOnBlur to false, it will not close.

ARIA Attributes#

  • If the trigger is set to click, the PopoverContent element has role set to dialog. If the trigger is set to hover, the PopoverContent has role set to tooltip.
  • The PopoverContent has aria-labelledby set to the id of the PopoverHeader.
  • The PopoverContent has aria-describedby set to the id of the PopoverBody.
  • The PopoverContent has aria-hidden set to true or false depending on the open/closed state of the popover.
  • The trigger has aria-haspopup set to true to denote that it triggers a popover.
  • The trigger has aria-controls set to the id of the PopoverContent to associate the popover and the trigger.
  • The trigger has aria-expanded set to true or false depending on the open/closed state of the popover.


Popover Props#

isOpenbooleanIf true, the popover is shown
defaultIsOpenbooleanIf true, the popover is shown initially.
initialFocusRefReact.RefThe ref of the element that should receive focus when the popover opens.
triggerhover, clickclickThe interaction that triggers the popover.
placementPopperJS.placementbottomThe placement of the popover.
returnFocusOnClosebooleantrueIf true, the popover will return focus to the trigger when it closes
closeOnBlurbooleantrueIf true, the popover will close when you blur out it by clicking outside or tabbing out
closeOnEscbooleantrueIf true, close the popover when the esc key is pressed
childrenReact.ReactNode, (props: InternalState) => React.ReactNodeThe children of the popover
gutternumber4The gap (in pixels) to apply between the popover and the target. Used by popper.js
usePortalbooleanfalseIf true the popover is displayed with a Portal. Rendering content inside a Portal allows the popover content to escape the physical bounds of its parent while still being positioned correctly relative to its target
onOpen() => voidCallback fired when the popover opens
onClose() => voidCallback fired when the popover closes

Other Props#

  • PopoverContent composes Box and has the ability to smartly position itself. Thanks to popper.js.
  • PopoverArrow, PopoverHeader, PopoverFooter and PopoverBody composes Box.
  • PopoverCloseButton composes CloseButton component.