Popovers are small overlays that open on demand. They let merchants access additional content and actions without cluttering the page.

Popover component examples

Use when presenting a set of actions in a disclosable menu.

import {Button, Popover, ActionList} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function PopoverWithActionListExample() {
  const [popoverActive, setPopoverActive] = useState(true);

  const togglePopoverActive = useCallback(
    () => setPopoverActive((popoverActive) => !popoverActive),

  const activator = (
    <Button onClick={togglePopoverActive} disclosure>
      More actions

  return (
    <div style={{height: '250px'}}>
          items={[{content: 'Import'}, {content: 'Export'}]}


interface PopoverProps

The content to display inside the popover.

preferredPosition?'above' | 'below' | 'mostSpace' | 'cover'

The preferred direction to open the popover.

preferredAlignment?'left' | 'center' | 'right'

The preferred alignment of the popover relative to its activator.


Show or hide the Popover.


The element to activate the Popover. If using a button, use the default or tertiary variant which will show an active state when popover is active.


Use the activator's input element to calculate the Popover position.

Defaults to true.


The element type to wrap the activator with.

Defaults to 'div'.


Override on the default z-index of 400.


Prevents focusing the activator or the next focusable element when the popover is deactivated.


Automatically add wrap content in a section.


Allow popover to stretch to the full width of its activator.


Allow popover to stretch to fit content vertically.


Allow popover content to determine the overlay width and height.


Remains in a fixed position.

ariaHaspopup?boolean | "false" | "true" | "menu" | "dialog" | "grid" | "listbox" | "tree"

Used to illustrate the type of popover element.


Allow the popover overlay to be hidden when printing.

onClose(source: ) => void

Callback when popover is closed.

autofocusTarget?'none' | 'first-node' | 'container'

The preferred auto focus target defaulting to the popover container.

Defaults to 'container'.


Prevents closing the popover when other overlays are clicked.


Prevents page scrolling when the end of the scrollable Popover overlay content is reached - applied to Pane subcomponent.

Defaults to false.

Best practices

Popovers should:

  • Always be positioned next to the button or other interface element that triggers them
  • Be used for secondary or less important information and actions since they’re hidden until merchants hit the trigger
  • Contain navigation or actions that share a relationships to each other
  • Be triggered by a clearly labeled button
  • Use a default or tertiary button as the activator

Content guidelines

Popover content

If a popover contains actions, they should:

  • Be clear and predictable: merchants should be able to anticipate what will happen when they click on an action item. Never deceive merchants by mislabeling an action.
  • Create order
  • Buy shipping label
  • New order
  • Buy
  • Be action-led: buttons should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK.
  • Rename
  • Edit HTML
  • Duplicate
  • HTML editing options
  • File name changes
  • Duplicate this order so that you can make edits, updates, or changes
  • Be scannable, especially when the popover contains a list of actions or options. Avoid unnecessary words and articles such as “the”, “an”, or “a”.
  • Add menu item
  • Add a menu item

If the popover includes a series of navigational links, each item should:

  • Be concise but still give merchants enough information so they can easily find and accurately navigate to the path they want.
  • Online store
  • Messenger
  • Facebook
  • Buy Button
  • Sales channel


Popovers usually contain an option list or an action list, but can also contain other controls or content.

To assist screen readers with sending focus to an action list, pass autofocusTarget='first-node' to Popover. This will avoid known issues a screen reader may have with keyboard support once focus is moved off the activator.

Web browsers assign a default value of 'menu' to the aria-haspopup role. You can use the prop ariaHaspopup to specify a value. Screen readers may fail to send focus to the Popover content when they expect the content to be adjacent to the element with aria-haspopup in the DOM tree. In this scenario, it is recommended not to provide the ariaHaspopup prop.

Keyboard support

  • When a popover opens, focus moves to the first focusable element or to the popover container
  • Once focus is in the popover, merchants can access controls in the popover using the tab key (and shift + tab backwards) and standard keystrokes for interacting
  • Merchants can dismiss the popover by tabbing out of it, pressing the esc key, or clicking outside of it
  • When the popover is closed, focus returns to the element that launched it

    On this page