Dialog

A Dialog opens from its trigger, such as a Button, and holds its title, which names it, a description, its content as children, and its own actions, after the built-in close button, with the primary action last.

• closeLabel names the close button; name it Cancel for a decision.
• Leave it uncontrolled, or control it with open and onOpenChange, which receives the requested state and why: the trigger, Esc, an outside press, the close button or a DialogClose.
• defaultOpen opens it on the first render.

Pending work

pending keeps the dialog open until it returns to false: Esc, outside presses and the close buttons don't dismiss it.

• It disables the built-in close button and every DialogClose inside.
• The last action, the primary one, shows it pending, where it is a Button that sets no pending of its own.
• Put a <form> in children and make the primary action its submit button, through the form attribute, so Enter in a field submits it too.

<Dialog
  title="Rename project"
  closeLabel="Cancel"
  pending={saving}
  actions={
    <Button type="submit" form={formId}>
      Save name
    </Button>
  }
>
  <form id={formId} onSubmit={save}>
    <TextField label="Project name" readOnly={saving} />
  </form>
</Dialog>

Closing actions

An action closes the dialog only where it is a DialogClose, a Button that closes it after its own onClick, or where it sets open to false. DialogClose takes Button's props and is secondary by default.

<Dialog
  title="Save changes to Launch plan?"
  closeLabel="Cancel"
  actions={
    <>
      <DialogClose onClick={discard}>Don’t save</DialogClose>
      <DialogClose variant="primary" onClick={save}>
        Save
      </DialogClose>
    </>
  }
/>

Placement, width and modal

placement is center, the default, or top, near the top of the window, so results grow down without moving the field.

• width is md, 28 rem and the default, or lg, 44 rem. Both narrow to fit the window.
• By default the dialog is modal: it traps focus over a backdrop, hides the page from assistive technology, blocks presses on it and locks its scroll. modal={false} leaves the page usable beside the dialog, such as an inspector.
• disablePointerDismissal keeps it open on presses outside it, and a non-modal one also when focus moves outside.

<Dialog width="lg" title="Review changes" trigger={<Button>Review</Button>}>
  …
</Dialog>

Focus

initialFocus sets where focus goes on opening, as a ref or a function of how it was opened; by default the first focusable element inside, and a confirmation's close button. finalFocus sets where it goes on closing, such as the row that opened it, where the trigger is gone or something other than trigger opened the dialog.

Keep one task per dialog: show a field's error on the field rather than in a second dialog over the first.

The parts are the surface, env-dialog, its heading, env-dialog-heading, with the title, env-dialog-title, the description, env-dialog-description, and the actions, env-dialog-actions, which start with the close button. The backdrop behind a modal dialog is env-dialog-backdrop.

The surface takes the popups' color and their shadow, --env-popup-shadow, as Popover describes, with no edge in light and their faint hairline in dark. It stays solid over the backdrop, so --env-popup-opacity and --env-popup-blur don't reach it. At high contrast, with reduced transparency and under forced colors it has no shadow and its level-3 elevation edge returns.