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


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 attribute | What it does |
|---|---|
.ph-dialog | A centred dialog, up to 520px wide |
.ph-dialog--sm / .ph-dialog--lg | Up to 400px / 760px wide |
.ph-dialog-header, -title, -description, -body, -footer | The dialog's parts |
data-ph-open="#id" | On any button: opens that dialog |
data-ph-close | Inside a dialog: closes it. A value (data-ph-close="later") becomes the dialog's returnValue. |
data-ph-static | On 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


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();
| Option | Default | What it does |
|---|---|---|
title | (required) | The question |
message | none | What happens if they confirm |
confirmLabel | "Confirm" | The confirm button's label. Name the action: "Delete dock". |
cancelLabel | "Cancel" | The cancel button's label |
danger | false | Makes 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


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>
| Class | Width |
|---|---|
.ph-drawer | 480px, full height, from the right |
.ph-drawer--lg | 720px |
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
| HTML | React (ph-app-kit-react) |
|---|---|
.ph-dialog | StyledDialog (open, onClose, title, actions), or FormDialog (onSubmit, submitLabel) |
.ph-drawer | FormDrawer 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.