The Popover component can be used for displaying supplemental or contextual interactive content over your UI. It is built on top of our Non-modal Dialog primitive. A Popover can contain a wide variety of information and interactive content and does not block the user from interacting with the rest of the page.
Popovers remain actively open until a user dismisses it in one of the following ways:
- Presses the Esc key
- Presses the close "x" button in the Popover
- Presses a "Cancel" button in in the Popover
- Clicks outside of the Popover
- Performs another action that closes the Popover
Popovers and non-modal dialogs follow these accessibility guidelines:
- A Popover must be triggered by an explicit user action, e.g., clicking a button.
- It must contain at least one focusable element, usually the close button.
- There should be a close button so screen readers have a specific close action to target.
- When a Popover is shown, focus is placed inside it, as it is a focus trap. A user cannot tab outside of the Popover until it is closed. After the Popover is closed, focus is placed back on the element that triggered it. Focus doesn’t return to the page until the user closes the Popover.
- The Popover should be labeled:
- Setting a value for the aria-labelledby property that refers to a visible Heading within the Popover .
- Providing a label directly specifying by aria-label attribute on the Popover.
- Popovers allow for much more dynamic content than Tooltips. They can display additional content that can contain interactive elements, like Buttons or Anchors. It is not possible to add interactivity inside a Tooltip. This is because a user cannot focus within a Tooltip; the content of the Tooltip is only visible when the trigger is hovered or focused.
- A Popover is opened on Click or Enter. A Tooltip is opened on Hover or Focus.
- If you want to provide a concise description of how or what an interactive element in your UI does, use a Tooltip.
- For displaying rich content or interactive elements, such as headings, anchors, or buttons, use a Popover.
For additional information on Tooltips, check out Heydon Pickering’s Inclusive Components guidance.
A Modal is a dialog that overlays the entire page. They can display interactive content, and place the users into a “mode” for inputting or reviewing information. It temporarily changes the user’s context for a more focused experience. We recommend using Modals to present critical information or request required input needed to complete a workflow instead of a Popover.
- For displaying contextual content, use a Popover. Popover content should be contextual to the page and be optional or supplementary. It should also be concise. For longer pieces of content, consider using a Modal instead.
- For a temporary change of context, use a Modal. Modals serve to place users into a “mode” or focused state for more complex interactions, inputting information, or displaying critical information.
- For displaying a series of steps that ask for user input or forms, use a modal over a Popover.
Use a Popover to display supplemental information and interactive controls.
The benefit of using a Popover is its ability to display interactive content to help provide additional information or functionality to your UI. It can essentially contain anything, like links, buttons, images, or headings.
When a user opens a Popover, the focus is set inside the Popover. By default, user focus is set on the first focusable element, which is the close button. You can choose to explicitly set focus to any focusable UI control inside the Popover.
We recommend the following when adjusting the focus:
- We caution against setting the focus on an element that does a non-reversible action, in case a user accidentally selects it. (e.g. an “Agree” button that a user hits by mistake, thinking they were exiting the Popover.)
- Changing the focus placement away from the close button could aid in more efficient in-context editing (e.g. the first text input).
To set a different initial focus target, set the initialFocusRef prop on the Popover component to a ref of a focusable element inside the Popover.
Use the placement prop to configure where to position the Popover in relation to its trigger. The available placement options are available in the props description here.
The Popover's width will grow to fit its content up to a maximum width of our size50 token. To set the size of the Popover, set a width prop. It will accept any valid size token up to size50.
The PopoverButton renders a Button component and accepts all of its props, which are listed on the Button page.
To launch a Popover from a Badge component, use the PopoverBadgeButton component. It renders a Badge and accepts all of its props except for as, which are listed on the Badge page.
This component should only be used as part of the filter pattern. It renders a FormPill and accepts all of its props, which are listed on the Form Pill Group page.
Popover comes with the option of "hooking" into the internal state by using the state hook originally provided by Reakit.
Rather than the state be internal to the component, you can use the usePopoverState hook and pass the returned state
to PopoverContainer as the state prop.
This allows you to use certain returned props from the state hook, including functions like hide and show.
An example usecase of this might be programmatically providing the user a popover when a certain user action is taken.
In the example below we are showing a popover when another button is pressed. When pressed the button uses the show
function from the hook. Another button using the hide function from the hook is also provided to hide the popover
when pressed.
It should be noted that when doing so, the state prop takes precedent over the other properties that affect the state or initial state of the Popover. They will be ignored in favour of them being provided as arguments to the usePopoverState hook.
For full details on how to use the state hook, and what props to provide it, follow the Non-Modal Dialog Primitive documentation. It's the same hook, just renamed.
To internationalize the Popover, pass different text as children to the Popover's contents and the aria-label prop. The only exception is the dismiss button. To change the dismiss button’s text, use the i18nDismissLabel prop.
Use a Popover to present supplemental information with interactive elements, like an Anchor. Information in a Popover should never be essential to task completion.
Popover content should use full sentences and punctuation. Titles are optional.
Do
Use Popover when you need to display supplemental interactive content over the top of your UI. It should have at least one focusable element.
Don't
Don’t present critical information or required inputs in Popovers, use the Modal instead.
Do
Use Popover to present additional contextual information that is not essential to completing a task.
Don't
After the Popover closes, don’t change the focus placement from the trigger. If focus is moved from the original trigger, it can cause confusion and frustration for where a keyboard user’s location is on the page.
Do
When the Popover is triggered, the focus should be placed on the first focusable element, which is usually the close button.
Don't
Don’t place Popovers on non-focusable elements, like an icon. Wrap them in a focusable element and place the Popover on that.
Do
Popovers should be triggered by a button.
Don't
Don’t place more than one primary action in a Popover.
Do
Consider the best size (up to size50) for the Popover container, based on its content.
Don't
Don’t use a Popover to guide users through a complex workflow with a series of steps or for presenting critical information. Use a Modal for workflows, and an Alert Dialog for critical information.