Dialogs and drawers

On this page

Dialogs ask for a little input or a decision without leaving the page. Drawers slide in from the right with more detail or a longer form. Both are native <dialog> elements: they trap focus, close with Esc, and dim the whole Performance Hub window when the app is inside it.

Dialog

A dialog with a formA dialog with a form

Figure 1: A dialog with a title, close button, one field and footer actions

<button type="button" class="ph-btn ph-btn--primary" data-ph-open="#invite">Invite member</button>

<dialog class="ph-dialog" id="invite" aria-labelledby="invite-title">
  <form method="dialog">
    <header class="ph-dialog-header">
      <h2 class="ph-dialog-title" id="invite-title">Invite member</h2>
      <button type="button" class="ph-icon-btn" data-ph-close aria-label="Close">...x icon...</button>
    </header>
    <div class="ph-dialog-body">
      <div class="ph-field">
        <label class="ph-label" for="invite-email">Email</label>
        <input class="ph-input" id="invite-email" name="email" type="email" />
      </div>
    </div>
    <footer class="ph-dialog-footer">
      <button type="button" class="ph-btn" data-ph-close>Cancel</button>
      <button type="submit" class="ph-btn ph-btn--primary" value="send">Send invite</button>
    </footer>
  </form>
</dialog>
Class or attributeWhat it does
.ph-dialogA centred dialog, up to 520px wide
.ph-dialog--sm / .ph-dialog--lgUp to 400px / 760px wide
.ph-dialog-header, -title, -description, -body, -footerThe dialog's parts
data-ph-open="#id"On any button: opens that dialog
data-ph-closeInside a dialog: closes it. A value (data-ph-close="later") becomes the dialog's returnValue.
data-ph-staticOn the dialog: clicking the backdrop or pressing Esc doesn't close it

Open and close from code:

phApp.dialog.open('#invite');
phApp.dialog.close('#invite');

When a dialog opens, focus goes to the element with autofocus, or else the first input. Clicking the backdrop closes it, unless it has data-ph-static.

Confirmation

A confirmation dialog for a destructive actionA confirmation dialog for a destructive action

Figure 2: A confirmation dialog for deleting a dock

phApp.dialog.confirm() builds the dialog for you and resolves to true when the person confirms:

const ok = await phApp.dialog.confirm({
  title: 'Delete this dock?',
  message: 'Booked deliveries are cancelled straight away.',
  confirmLabel: 'Delete dock',
  danger: true,
});
if (ok) await deleteDoor();
OptionDefaultWhat it does
title(required)The question
messagenoneWhat happens if they confirm
confirmLabel"Confirm"The confirm button's label. Name the action: "Delete dock".
cancelLabel"Cancel"The cancel button's label
dangerfalseMakes the confirm button red, and starts focus on Cancel

The confirm button has focus when the dialog opens, unless danger is set. Then Cancel has focus, so a stray Enter can't delete anything.

Drawer

A drawer showing a dock's detailsA drawer showing a dock's details

Figure 3: A drawer with a record's details and actions

A drawer is the same markup with .ph-drawer instead of .ph-dialog:

<dialog class="ph-drawer" id="details" aria-labelledby="details-title">
  <form method="dialog">
    <header class="ph-dialog-header">...</header>
    <div class="ph-dialog-body">...</div>
    <footer class="ph-dialog-footer">...</footer>
  </form>
</dialog>
ClassWidth
.ph-drawer480px, full height, from the right
.ph-drawer--lg720px

On phones, drawers take the full width.

Inside Performance Hub

When the app runs inside Performance Hub, opening a kit dialog or drawer also dims Performance Hub's own navigation around the app, so the whole window reads as one modal. Clicking that dimmed area closes the dialog, like clicking the app's own backdrop. This needs no code.

React

HTMLReact (ph-app-kit-react)
.ph-dialogStyledDialog (open, onClose, title, actions), or FormDialog (onSubmit, submitLabel)
.ph-drawerFormDrawer or DrawerShell (open, onClose, title, footer)

Guidelines

  • Title dialogs with what they do ("Invite member") or the question ("Delete this dock?").
  • Confirm buttons name the action. Never "OK" or "Yes".
  • Confirm destructive actions and say what's lost. Don't confirm things that are easy to undo; offer Undo in a toast instead.
  • Use a drawer when people need the page behind it for context, or the form is long.
  • Don't stack dialogs on dialogs.