Popover is a floating view that contains a task related to the content on screen. It can be triggered when the user clicks or focuses on an element, typically Button or IconButton. It can also be triggered automatically, as in the case of user education. Popover is non-modal and can be dismissed by interacting with another part of the screen or an item within Popover.
Popover is most appropriate for desktop screens and can contain a variety of elements, such as Button and Images. Popover is also the container used to construct more complex elements like Dropdown and the board picker, pictured below, which allow people to choose the board to save a Pin to.
- When Popover opens, focus moves to the first focusable element in the Popover container.
- Popovers are also a focus trap, so users should only be able to interact with the content inside the Popover container.
- Popover should always be dismissible using the ESC key. It could also be dismissed by interacting with another part of the screen, or by interacting with an element inside Popover.
- When Popover is closed, focus returns to the anchor element that triggered Popover.
To assist screen readers, we recommend passing the following ARIA attributes to the anchor element:
accessibilityHaspopup: informs the screen reader that there’s a Popover attached to the anchor element. It populates aria-haspopup.
accessibilityExpanded: informs the screen reader whether Popover is currently open or closed. It populates aria-expanded.
accessibilityControls: match with the
idof the associated Popover whose contents or visibility are controlled by the interactive component so that screen reader users can identify the relationship between elements. It populates aria-controls.
For role attribute, use:
- 'dialog' if the Popover is a dialog that prompts the user to enter information or requires a response.
- 'menu' if the Popover presents a list of choices to the user.
- 'listbox' if the Popover is a widget that allows the user to select one or more items (whose role is option) from a list. May also include a search option.
Be sure to localize any text elements within Popover. Note that localization can lengthen text by 20 to 30 percent.
The maximum width of Popover. Popover has different size configurations:
number: Use this prop to create custom-size Popovers in pixels.
flexible: Use this configuration for larger Popovers. Without a defined maximum width, Popover grows to fit the content in
We recommend using
"xs" for education Popovers and
"xl" for more complex Popovers. Avoid using other configurations whenever possible as they are legacy sizes.
Color and caret
When building in-product education, be sure to pass in
showCaret="true", as seen in the first example, and use Experience HQ for the configuration. For Popovers that aren’t education, use the default
showCaret="false", as seen in the second example. Avoid using any other configurations as they are legacy colors.
Popover requires a reference element, typically Button or IconButton, to set its position. The
anchor ref can be directly set on the reference component itself. If the components don’t support
ref, the anchor ref can be set to a parent Box.
Popover calculates its position based on the bounding box of the
anchor. Therefore, the
anchor ref should only include the trigger element itself, usually Button or IconButton, or the specific feature component that requires an educational Popover.
Popover is typically used within Layer. Layer renders Popover outside the DOM hierarchy of the parent allowing it to overlay surrounding content. Popover calculates its position based on the bounding box of the
anchor. Within Layer, Popover no longer shares a relative root with the
anchor and requires
positionRelativeToAnchor=false to properly calculate its position relative to the anchor element.
Layer with Popover eliminates the need to use
z-index to solve stacking context conflicts. Popovers within Modals and Sheets with z-indexes don't require
Layer thanks to the built-in ScrollBoundaryContainer.
idealDirection as necessary to ensure the visibility of Popover and its contextual information. The default direction is "up", although Popover should be center-aligned directly below the element in most cases. The actual position may change given the available space around the anchor element.
Within scrolling containers
ScrollBoundaryContainer is needed for proper positioning when Popover is anchored to an element that is located within a scrolling container. The use of ScrollBoundaryContainer ensures Popover remains attached to its anchor when scrolling.
Dropdown is an element constructed using Popover as its container. Use Dropdown to display a list of actions or options in a Popover.
Toast provides feedback on an interaction. One example of Toast is the confirmation that appears when a Pin has been saved. Toasts appear at the bottom of a desktop screen or top of a mobile screen instead of being attached to any particular element on the interface.
Tooltip describes the function of an interactive element, typically IconButton, on hover. While Popovers offer broader content options, such as Button and Images, Tooltips are purely text-based.
ScrollBoundaryContainer is needed for proper positioning when Popover is anchored to an element that is located within a scrolling container. The use of ScrollBoundaryContainer ensures that Popover remains attached to its anchor when scrolling. See the within scrolling containers variant to learn more.