GitHub icon

<State initial={false}>
	{([open, setOpen]) => (
		<div>
			<Button onClick={() => setOpen(true)}>Live Demo</Button>
			<Dialog
				open={open}
				onClose={() => setOpen(false)}
				title="Closable Dialog"
				onPrimaryActionClick={() => setOpen(false)}
				primaryActionName="Save"
				onSecondaryActionClick={() => setOpen(false)}
				secondaryActionName="Cancel"
			>
				Both buttons in this demo will close the dialog.
			</Dialog>
		</div>
	)}
</State>

Negative / Destructive

The dialog's primary action can signify a destructive action. Negative dialogs contain two actions.

Actions

Dialogs require at least one action, with no more than two.

When only one action is provided, it is an acknowledgement action.
When two actions are provided, the primary action is a confirming action, and the secondary a dismissing action.

Non-closable Dialog

Dialog should be closable in most cases, by clicking on the background around the dialog. For other cases, non-closable Dialog can be implemented removing onClose prop. This creates a mandatory action in a workflow.

Dialog Examples

Examples with Two Actions

<Dialog
	open
	focusTrapOptions={{ disabled: true }}
	title="Confirmation"
	portal={false}
	onPrimaryActionClick={() => {}}
	primaryActionName="Continue"
	onSecondaryActionClick={() => {}}
	secondaryActionName="Cancel"
>
	<p className="m-t-0">You are about to save changes to an active template. It may take a while for the changes to take effect in Inventory.</p>
	<p>Would you like to continue?</p>
</Dialog>

<Dialog
	open
	focusTrapOptions={{ disabled: true }}
	title="Delete Report"
	portal={false}
	onPrimaryActionClick={() => {}}
	primaryActionName="Delete Report"
	onSecondaryActionClick={() => {}}
	secondaryActionName="Cancel"
	negative
>
	<p className="m-t-0">You have 3 scheduled reports for Accounts Receivable Summary by Invoice Type.</p>
	<p>Deleting this report will also delete its scheduled reports.</p>
</Dialog>

Examples with One Acknowledgement Action

Content Guidelines

Write titles as verbs

Titles should have a clear verb + noun question or statement.

Edit customer information

Delete message?

Discard unsaved changes?

Edit the service agreement for this customer

Are you sure you want to remove the invoice?

Delete?

Make body content concise and actionable

Use imperative verbs when telling users what they need to know or do. Don’t use permissive language like "you can".

Notification emails will be sent to this address.

This cannot be undone.

You can edit the email address where emails will be sent.

Are you sure you want to delete this job? You can’t reverse this.

Buttons should be clear, predictable, and action-oriented

Users should be able to predict what will happen when they click a button.

Lead with a strong verb that encourages action. Use a verb/noun pair on actions in most cases. Common actions like Save, Close, or Cancel do not require an accompanying nou

Dialogs are more restrictive in their options relative to modals.

Can only be X-Small in size.
Cannot have scrolling content.
Cannot have the close icon × in the top right.
Must have one or two actions.
The footer can only be right aligned, with only solid-filled buttons.
Only the primary action button can be customized: primary solid or negative solid.
Body content is optional.

Best Practices

Dialogs should only be used if they require the user to be interrupted.
For actions, avoid 'Yes' and 'No' responses.
If an action involves cancelling an operation, it should be the secondary action, usually labeled 'Cancel'.
Like modals, dialogs should be used sparingly. Particularly with one action dialogs.

For more complex interactions that require user interruption, use a Modal.
To completely hide the context of the page, use a Takeover component.
For information that does not require user interruption, use a Toast or Banner notification.

Dialog