Components

Popover

Overview

When to use

Provide additional useful but non-critical information and actions about referring elements.

When not to use

Consider if placing the content within a popover is needed at all. It might be more helpful to have the content inline and visible by default.

For short, non-actionable information, consider using a tooltip.

Principles

A popover is used to provide useful information about an element, including one or multiple actionable elements. It gives the user additional information without forcing them to act upon it like in a dialog.

A popover is opened by clicking on an element that has the popover attached to it. Do not trigger popovers on hover as they may contain interactive elements and some users may find it difficult to interact with those elements.

A popover can be dismissed by clicking on the close button within it, clicking outside of it or pressing the Esc key on the keyboard.

The title of a popover should be clear and concise and preferably fit to one line, or 2 lines at maximum. Try to keep the content of a popover also as short as possible.

Only one popover can be visible at a time.

Having a title in a popover is recommended, but it may be omitted if needed.

Size

On mobile screens the popover has the same width as the content area, by default. The width may be reduced if needed.

On larger screens the default width is 400px. This may be reduced or increased if needed, but should not exceed 600px.

The height of the popover is determined by the content and should never exceed the height of the viewport. Try to keep the height below 400px.

Placement

By default, popovers should be placed above the referring element. When there isn't enough space in the viewport, the popover is moved to the side or below as needed.

Pointer

Popover has a pointer to help show the relationship between the popover and where it was triggered from.

There are predefined positions for start, center and end. Position of the pointer may also be adjusted manually if needed.

Interactive content

Popover can contain links and buttons.

Custom content

Popover can also contain custom content.

Usage

Usage guidelines

Short content

Don’t use a popover for simple labeling, i.e. providing a label for the icon button. Use a tooltip instead.

Do

Don't

Position

Make sure that the popover is always fully visible inside the viewport.

Do

Don't

Size

Keep the width of the popover below 600px. Do not stretch it to 100% of viewport width (except on mobile screens).

Do

Don't

Accessibility

Keyboard

• Activating the toggle button (data-popover-toggle) opens the popover and moves focus to its first focusable element, usually the close button.
• Tab moves through the popover's controls and then on to the rest of the page. The popover is not modal, so focus is not trapped, and the popover stays open.
• Escape closes the popover and returns focus to the toggle.
• The close button also closes it and returns focus to the toggle.
• Clicking outside the popover closes it without moving focus.

Screen readers

The popover has role="dialog" and is named by its title, or by its content when there is no title, through aria-labelledby. The toggle's aria-expanded announces whether it is open, and the script adds aria-controls pointing at the popover. The close button is named by closeLabel ("Close popover"). The pointer arrow and close icon are aria-hidden="true".

Using the example

• Popover ids must be unique, and each toggle's data-popover-toggle must match its popover's id.
• closeLabel defaults to English; pass an Estonian name, such as "Sulge", on Estonian pages.
• Keep popovers short and non-blocking. When the user must answer before continuing, use a dialog.
• The documentation examples have no toggle, so they stay visible until closed. Always give real popovers a toggle, or keyboard users cannot reopen them.

Known limits

The footer buttons ("Cancel", "Action") have no behaviour. Your code must perform the action, close the popover and return focus to the toggle.