Popover

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

Examples

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

Drag to resize example

Props

activatorRequired
ReactElement
The element to activate the Popover
activatorWrapper
string
The element type to wrap the activator with
activeRequired
boolean
Show or hide the Popover
ariaHaspopup
false | true | "dialog" | "menu" | "true" | "false" | "grid" | "listbox" | "tree"
Used to illustrate the type of popover element
autofocusTarget
"none" | "first-node" | "container"
The preferred auto focus target defaulting to the popover container
children
React.ReactNode
The content to display inside the popover
colorScheme
"light" | "dark"
Accepts a color scheme for the contents of the popover
fixed
boolean
Remains in a fixed position
fluidContent
boolean
Allow popover content to determine the overlay width and height
fullHeight
boolean
Allow popover to stretch to fit content vertically
fullWidth
boolean
Allow popover to stretch to the full width of its activator
hideOnPrint
boolean
Allow the popover overlay to be hidden when printing
preferInputActivator
boolean
Use the activator's input element to calculate the Popover position
preferredAlignment
"left" | "right" | "center"
The preferred alignment of the popover relative to its activator
preferredPosition
"above" | "below" | "mostSpace"
The preferred direction to open the popover
preventFocusOnClose
boolean
Prevents focusing the activator or the next focusable element when the popover is deactivated
sectioned
boolean
Automatically add wrap content in a section
zIndexOverride
number
Override on the default z-index of 400
onCloseRequired
(source: PopoverCloseSource) => void
Callback when popover is closed

Accessibility

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

Popover with action list

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

Popover with action list for Android

Popover with content and actions

Use to present a combination of content, instructions, and actions in a panel for tasks that are of low or secondary importance to the current page. When used this way, popovers provide useful entry points to related features without overwhelming merchants.

Popover with content and actions for Android

Accessibility

See Material Design and development documentation about accessibility for Android:

Popover with action list

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

Popover with action list for iOS

Popover with content and actions

Use to present a combination of content, instructions, and actions in a panel for tasks that are of low or secondary importance to the current page. When used this way, popovers provide useful entry points to related features without overwhelming merchants.

Popover with content and actions for iOS

Action sheet

Use when you have few actions that affects the whole page. Action sheets doesn’t support icons or additional information.

iOS action sheet

Accessibility

See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

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

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

Edit source on GitHub