Overview

A Popover is a localized, non-modal container that pops up over all other elements on a page to convey additional content and actions.

User stories

• As a user, I need additional space to provide information or interactivity based on an existing element on the page.

Component task owners

• Designer: @DTorsani-WMF
• Developer: @lwatson

Potential use cases

	Growth implementation in Vue (See related task T340199)
	Popups with different content in Wikipedia.
	Popover to show user account reputation score data (see T384702)
	Popover to surface structured tasks to readers (see T376680)

Codex implementation

Component scope

The initial component will have the following features:

• A target element that opens the Popover. The target element is triggered on hover or toggle. This can be a toggle button or a link triggered on hover (eg. Wikipedia link previews).
  • If the target element is a toggle button, ensure the toggle button has a type="button" to prevent browsers from mistaking the button as a submit button when placed inside forms.
• A live region to announce the Popover information.
• Use Floating UI to absolutely position the Popover to the target element.
• Customize with a title, close button, text, and actions.
• Customize by including images (eg. Wikipedia link previews).
• Customizable layouts such as vertical and horizontal (eg. Wikipedia link previews).
• An optional caret tip that points to the triggering element (opt-in to use this feature). Refer to Floating UI's arrow to position the caret tip.

API:

• Slots: header, body, and footer.
• Props: open, title, useCloseButton, closeButtonLabel, props related to actions and their layout, target (similar to Dialog).

Open questions

• Regarding focus behavior and tab order, what is the expected behavior for entering and exiting the focus of the Popover when using a keyboard?
• Define the user flow when interacting with elements in the background.
  • Option 1: First lose the focus of the Popover, then interact with other elements. Example: When a Popover is visible, clicking on a link in the background will close the Popover.
  • Option 2: Instantly able to interact with other elements. Example: When a Popover is visible, clicking on a link in the background will close the Popover and navigate to another page.
• In OOUI, the PopupButton uses the title HTML attribute. Should the Popover use the title attribute? And do we style it similarly to the Tooltip?
• In mobile, Popover appears as a bottom sheet and there are known issues with bottom sheets in iOS. Do we include the mobile-friendly version in the MVP?
• Does this need a global event handler for the Escape key?
• Does it need to be aware of the teleport target like the Dialog?
• Does this need to have a z-index different than tooltip? Is the popover from a user logic stacked above or below a toast notification – tooltip right now is 800, toast notification 900?

Design spec

Guidelines

Demos

Designer should describe how the component should be documented in the demos, including configurable and standalone demos.

Acceptance criteria

Minimum viable product

This task covers the minimum viable product (MVP) version of this component. MVP includes basic layout, default states, and most important functionality.

Design

• Implement the component in Figma

Code

• Implement the Vue component in Codex
• Add the WIP component
• Add a basic demo to Sandbox
• Add snapshot and unit tests
• Add demo page with guidelines and code examples