# Popover

> A transient surface attached to a control, holding information or a small task.

A popover is a transient surface attached to a control, holding information or a
small task — a few settings, a short form — related to that control.

## When to use

Use a popover for a task that is small and closely tied to one control, where
leaving the current view would be disproportionate. When the content is a list
of commands, use a [menu](https://ui.publictheta.com/components/menu.md). When the task demands a decision
before anything else can continue, use a [dialog](https://ui.publictheta.com/components/dialog.md).

## Best practices

**Keep it small.** A popover should hold one task. If it needs scrolling or
navigation of its own, it wants to be a view.

**Name it.** A popover is a dialog: give it a name, from a visible heading or a
label, so it is announced for what it is.

**Commit changes as they are made, or offer a clear way to finish.** Closing a
popover by Escape or a press outside should not lose work that people expect to
keep; where changes must be confirmed, provide the button that confirms them.

**Open it from a control that says so.** The control states that it opens a
dialog and whether it is open.

**Give a close button a name.** A button that closes the popover and shows only
a mark — a cross — is named in words, in the language of the interface. One
that carries its own label, such as Done or Cancel, is styled as the task's
other buttons are.

## Platform considerations

**Pointer and keyboard.** The popover appears beside its control. Focus moves to
its first control, Tab moves through its contents, and Escape closes it and
returns focus to the control that opened it. It needs no close button of its
own, and has none unless it is given one.

**Touch, on a phone.** The popover rises from the bottom edge as a sheet, across
the full width, above a dimmed interface. There the page behind is inert and
there is no Escape key, so a popover always has a button that closes it: one
that was given none has a close button at its top corner, clear of its content
and at least 44 CSS pixels across. It comes last in the order of focus, so that
opening the popover still puts focus on its own first control.

See also [Overlays](https://ui.publictheta.com/foundations/overlay.md).

## Behaviour

Each statement is verified by a test in Chromium, Chromium (touch), Firefox, WebKit, WebKit (touch), unless it names the environments it applies to or is marked open.

### Semantics

- The control states that it opens a dialog, and whether it is open.
- The popover is a dialog with its name.
- Has no accessibility violations when open.

### Focus

- Opening moves focus to its first control.
- Tab moves through its controls.
- A close button closes it and returns focus to the control that opened it.
- Escape closes it and returns focus to the control that opened it.

### Closing

- A close button given no label is an icon button named in words, and closes it.
- On a phone, where it is a sheet, one given no close button has one all the same, last in its order. *(Chromium (touch), WebKit (touch))*
- On a phone, one given a close button has only that one. *(Chromium (touch), WebKit (touch))*
- With a pointer, one given no close button has none. *(Chromium, Firefox, WebKit)*

### Presentation

- With a pointer, it sits against its control. *(Chromium, Firefox, WebKit)*
- On a phone, it rises from the bottom edge across the full width. *(Chromium (touch), WebKit (touch))*

## Reference implementation

React: `npx shadcn@latest add https://ui.publictheta.com/r/popover.json`