Popover

Accessibility and usability expectations

Popover is a container that is visually positioned near a related element and sits above the rest of the page content. Unlike a Dialog, it does not visually obscure the rest of the page and does not trap focus.

When you use Popover, ensure that:

• The Popover is operable using the keyboard alone.
• When the Popover opens, focus moves into it (typically to the first focusable control). If the Popover has no focusable controls, move focus to a container within the Popover that has tabindex="-1" declared on it.
• When the Popover closes, focus returns to the interactive element that triggered it.
• The Popover can be dismissed using Esc as well as a visible control or click-outside.
• The Popover follows its related element in the DOM order, so screen readers encounter the content in the right order.

Built-in accessibility features

The component renders a styled container with a visual pointer (the caret). Beyond visual styling, it has no built-in accessibility features.

Specifically, the component does not:

• Set a role
• Manage focus when opened or closed
• Handle Esc to dismiss
• Hide other page content from assistive technology

Popover.Content exposes an onClickOutside callback that can dismiss the Popover when the user clicks outside it. Note that this is a mouse-only mechanism; you must also handle keyboard dismissal yourself.

Implementation requirements

Choose an appropriate role

Popover does not set a role, and the right choice depends on what the Popover contains and how it's used. Common choices include:

• role="complementary" if it presents tangential information related to the surrounding content
• role="dialog" if it contains a form or task with focusable controls
• role="status" if it announces a status change
• No role at all if the surrounding context already conveys the structure

Don't use Popover itself to imply semantics. Pick a role that matches the content's purpose, or wrap the Popover in a more semantic element.

Manage focus

When the Popover opens, programmatically move focus into it. When it closes, return focus to the trigger that opened it. See Focus management for guidance.

Handle keyboard dismissal

Listen for Esc while the Popover is open and use it to close the Popover, in addition to the onClickOutside callback.

Provide a visible dismiss control

If the Popover provides additional information (rather than wrapping a focusable form, for example), include an explicit dismiss control such as a "Got it" or close button so users do not have to know the keyboard shortcut.

Place the Popover after its related element in the DOM

Place the Popover immediately after the element it relates to in the document source. This ensures screen readers and keyboard users encounter the Popover content in the correct order, since the component does not move focus on its own.

How to test the component

Integration tests

• The Popover follows its related element in the rendered document structure
• If the Popover contains focusable controls, they appear in a logical focus order after the trigger
• The Popover has a role appropriate to its content, or no role if its content already conveys structure
• Focus moves into the Popover when it opens
• Focus returns to the trigger when the Popover closes
• The Popover can be dismissed using Esc
• The Popover can be dismissed by clicking outside it
• If the Popover presents additional information rather than wrapping a focusable form, a visible dismiss control is available