Popover

v1.0.0 | View in Storybook

​

When to use

• For lightweight, contextual content or actions: Use Popovers to show information or actions directly related to a specific trigger (Button, icon, text).
• When you want to keep users in context: Popovers are non-blocking and allow users to stay on the same screen without major interruptions.
• To display additional details or previews on demand: For example, previewing user profile details on hover or click.
• When you need more space than a tooltip, but less than a Dialog: Popovers can hold controls like Buttons, which can provide additional links to more information or confirmative actions like a soft (non-destructive) delete.

​

When to use something else

• Brief, passive hints on hover/focus with no controls inside: use Tooltip.
• Full attention, blocking flow, or critical decisions: use Dialog / Alert dialog or a dedicated page.
• Choosing from a list of commands or values: use Menu or Select, not a generic Popover.

​

Dos and don’ts

• Do anchor the Popover clearly to a trigger element.
• Do use a Popover for secondary or optional tasks as they should enhance the primary workflow, not interrupt it.
• Do be mindful of screen boundaries and reposition the Popover if necessary as it should be fully visible when triggered without the user having to scroll to see it.
• Don’t block essential content behind the Popover, or make sure the user can move the Popover to see the content.
• Don’t allow more than one Popover to be displayed at a time.

​

Behavior

• Non-modal overlay anchored to a trigger; dismisses on outside click and Escape unless the design requires persistent multi-control content.
• Repositions to remain in the viewport; may allow drag in implementations that support it—don’t obscure essential content without a way to reveal it.

​

Often used with

Button or subtle text trigger; compact forms (Input, small Button); not a substitute for Menu command lists.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Sides

Position the popover on different sides of the trigger depending on available viewport space and what content must remain visible.

​

Alignment

Fine-tune alignment so the popover edge lines up with the trigger—useful when the trigger is narrow or sits near layout boundaries.

​

With form

Embed a compact form inside a popover for quick edits or secondary inputs without navigating away from the current view.

​

Custom width

Set a custom width when default sizing is too narrow for form fields or too wide for short explanatory content.

​

Rich content

Use rich content—headings, lists, or actions—when the popover needs more structure than a single line of text or one button.

​

Controlled

Use a controlled popover when open state must sync with application logic, such as guided tours, URL parameters, or parent form state.

​

Empty content

Avoid shipping empty popovers in production; use this pattern only as a placeholder while content is being wired up.

​

Long content scrollable

Allow scrolling inside the popover when content exceeds the viewport so users can read everything without the panel growing off-screen.

​

Narrow viewport

Test popover behavior on narrow viewports so repositioning and scrolling keep the panel fully visible and usable on small screens.