# Dialog

> A modal surface over the whole interface, for a task or a question that must be finished or dismissed first.

A dialog is a surface over the whole interface for a task or a question that
must be finished or dismissed before anything else: a confirmation, a short
form. An alert is a dialog that interrupts to warn, and asks for an answer.

## When to use

Use a dialog when the interface cannot go on until something is decided —
before what cannot be undone — or for a task that needs the person's whole
attention for a moment. For a small task beside the control it belongs to, use
a [popover](https://ui.publictheta.com/components/popover.md), which leaves the rest of the interface in
reach. For a list of commands, a [menu](https://ui.publictheta.com/components/menu.md).

## Why it is a component

A [popover](https://ui.publictheta.com/components/popover.md) is also a dialog, on the same [overlay
primitive](https://ui.publictheta.com/foundations/overlay.md), but it differs in each of the things that
make a dialog what it is:

- **Not anchored.** A dialog is about the whole task, not one control: it sits
  in the middle of the view, whatever opened it — a button, a menu command, the
  application itself.
- **Always modal.** The page behind it is inert and still on every screen, not
  only on a phone; a press outside reaches nothing beneath. A popover lets the
  rest of the page be used.
- **Its own role and name.** It is announced as a modal dialog, or an alert
  dialog, named by its title and described by its description.
- **Its own focus rules.** Focus opens on its first control — in an alert, on
  Cancel — whether the dialog was opened by its control or by its owner's
  state.

What the two share — the dismissal stack, focus moved in and brought back,
sheets on phones, the page held inert and still — is the overlay primitive's,
which grew the blocking and the alert's indifference to a stray press for it.

## Best practices

**Title it, and say what it is about.** The title names the dialog; a sentence
or two under it is its description. An alert's title is the question: Remove
three files?

**Name the way out.** The buttons say what they do — Remove, Cancel — not Yes
and No. The one that destroys is the danger button, and is not where focus
opens.

**Keep it short.** A dialog that needs scrolling or steps of its own wants to be
a view.

**Do not open one dialog over another** unless the second is a question about
the first.

## Platform considerations

**Pointer and keyboard.** The dialog sits in the middle of the view over a
dimmed interface. Focus moves to its first control — to Cancel in an alert — or
to the dialog itself when it has nothing to operate. Tab moves through it and
does not reach the page behind. Escape closes it, an alert too, and focus
returns to what opened it, or, opened by its owner, to what had focus before. A
press outside a dialog closes it and does nothing else; a press outside an
alert does nothing, and focus stays where it was. Where a scrollbar takes room,
the page does not shift sideways as the dialog opens.

**Touch, on a phone.** The dialog rises from the bottom edge as a sheet, which
is dragged away as any sheet is. With no Escape key, it always has a button
that closes it: one given none has a close button at its top corner, last in
the order of focus and 44 CSS pixels across.

**Assistive technology.** It is a modal dialog, or an alert dialog, named by its
title and described by its description; the page behind it is inert. The
control that opens it says that it opens a dialog, and whether it is open.

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.
- It is a modal dialog, named by its title and described by its description.
- An alert is an alert dialog.
- Has no accessibility violations when open.
- Has no accessibility violations when open as an alert.
- One given no title is reported while developing.

### Focus

- Opening moves focus to its first control.
- An alert opens with focus on its Cancel, so that a habitual Return does not do what it warns of.
- With nothing to operate, focus moves to the dialog itself.
- Opened by its owner rather than its control, focus still moves to its first control.
- Escape closes it and returns focus to the control that opened it.
- A close button closes it and returns focus to the control that opened it.

### Modality

- While it is open the page behind is inert, and afterwards exactly as it was.
- Tab does not take focus to the page behind it.
- The page behind does not scroll while it is open, and scrolls again once it closes.
- Where a scrollbar takes room, it keeps its room while the page is held still; where none does, none is made. *(Chromium, Firefox, WebKit)*

### Dismissal

- A press outside closes it, and does not press what it lands on.
- A press outside an alert leaves it open, with focus where it was.
- Escape closes an alert too: it is the same as Cancel.
- With a popover open inside it, Escape closes the popover alone.

### Presentation

- With a pointer it sits in the middle of the view, not against its control. *(Chromium, Firefox, WebKit)*
- On a phone it rises from the bottom edge across the full width. *(Chromium (touch), WebKit (touch))*
- On a phone, one given no close button has one all the same, last in its order and 44 pixels across. *(Chromium (touch), WebKit (touch))*
- With a pointer, one given no close button has none. *(Chromium, Firefox, WebKit)*

## Reference implementation

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