Skip to content

Popover

Popover is a smaller variant of Dialog that can be used for simple, context-related actions and filters.
Figma logo
Anatomy of a Popover: header on top, body in the middle, footer along the bottom
Popover and its sub-components
Anatomy of the Popover component
ElementPurpose
HeaderHeader is pinned to the top of a Popover and content scrolls below when needed.The PopoverHeader component is used to add a heading.
Close actionThe close action is built into the PopoverHeader sub-component and should always be added even if a heading isn’t used.
BodyBody content can contain almost any element, such as text, form elements, images, or other components. Body content lives inside the PopoverBody component.
FooterFooter is pinned to the bottom of a Popover and content scrolls below when needed. When using Actions, add them to the PopoverActions component inside PopoverFooter.
ActionsPrimary actions typically are used to apply changes or submit a form, while secondary actions cancel any changes and close the Popover. Actions are always right-aligned in Popover and should live within the PopoverActions component.
  • Note the usage of usePopover, which returns required properties for the opening button element and the Popover itself
  • Add an aria-label to the Popover element to help screen reader users decide whether or not they want to interact with the element
React props
NameTypeDefaultDescription
children  RequiredReactNodeThe content of the Popover.
onClose  funcCallback triggered when closing the Popover. Applies to clicking the close action, clicking the backdrop, and pressing the esc key. Can also be called with popoverProps.onClose()
open  booleanfalseIf true, the Popover will be shown.
persistent  booleanfalseBy default Popovers behave like pseudo-pages in the application whose children are not mounted until they are opened in order to reset state and to prevent loading data unnecessarily. If persistent is set, the Popover will mount immediately and stay mounted until it is removed by a parent element, similar to a standard component. This is useful for SEO and for keeping frequently accessed Popovers fast and responsive.
placement  autoauto-startauto-endtoptop-starttop-endbottombottom-startbottom-endrightright-startright-endleftleft-startleft-endbottom-startPopper.js placement option. For more information see the Popper.js docs.
reference  RequiredHTMLElementHTMLElement used to position the Popover.
Popover sub-components
Sub-componentPurpose
PopoverHeaderHeader at the top of the Popover; contains the close action
PopoverBodyWrapper around Popover body content
PopoverDescriptionText announced to a screen-reader when the Popover is opened
PopoverFooterWrapper around Popover footer content; anchored to the bottom of the Popover
PopoverActionsSimilar to Actions, but for Popovers. Actions will be reordered based on viewport size.

Popover was built with accessibility in mind.

  • Popovers are positioned relative to their “reference” (opening) element to maintain a visual connection between the elements
  • A Popover must be self-sufficient and not rely on context outside of itself
    • Screen readers will not have access to content outside of the Popover
    • The Popover will be layered above other content, which will present a challenge for sighted users
  • Popover content will not be read allowed when opened
    • Popover content is typically form-heavy and not well-suited to being read aloud
    • The PopoverDescription component can be used for text that should be read allowed when the Popover is opened

Popover shares a foundation with Dialog. Suggestions for testing Dialog also apply to Popover.