Modal

Best Practices

Modals should:

• Provide the user with clear paths forward and/or out of the modal.
• Provide tabbable elements in the dialog context when providing content for editing.

Modals should not:

• Create a “wizard” flow with two or more steps. Instead, favor full-page layouts for “wizard” style flows.
• Use custom z-indices. See more about layering in our theming guide.

Content

A standard Modal has the following anatomy:

The areas within a modal can be populated either by providing the relevant props (headerText, submitLabel, dismissLabel etc), or by providing the following content components to your modal as direct descendants to the modal:

• EzPreview (image or illustration)
• EzHeader (title and other header content e.g. card actions)
• EzContent (body)
• Footer.

The EzHeader, EzContent, and EzFooter content elements accept any renderable node, not just strings, allowing you to create dialogs for more complex workflows.

A modal can be shown or hidden using the isOpen prop.

Example

Informational modal

Informational modals are used to focus the user’s attention on specific information.

Use this variant when presenting information that is not essential to the completion of the actions on the page. This variant can be useful when there is otherwise too much content to display in a tooltip, or where content formatting is needed.

Provide a both the dismissLabel prop and the onDismiss prop to present the user with a close button and enable the dialog to be automatically closed when clicking away or when pressing the escape key.

Editing modals

Editing modals can contain any form elements and should be kept as brief as possible. Long or complex forms should almost always be done in a new section/page instead of a modal. Editing modals are suitable for prompting the user to take a specific action before they are allowed proceed with their regular page interactions.

The onSubmit function will be called when the user clicking the button labelled by the provided submitLabel.

Confirmation modals

Use a confirmation modal to ask the user to confirm changes they’re about to make or confirm a destructive action they’re about to take.

• Use destructive buttons to clearly designate actions with destructive consequences
• Provide a cancel option with a clear label. Make sure the copy isn’t confusing when placed next to a destructive action (cancel order, cancel).
• Provide appropriate detail so the user can make an informed decision.

The destructive prop should be used to indicate that the onSubmit function is destructive.

Required action modals

Use a required action modal only when the user must accept or submit the modal information to move forward on the site.

• Use sparingly as the modal will block use of the site until submitted. Most use cases for required actions should original from our legal team.

A required action modal will be presented when both of the following conditions are met:

• The dismissLabel prop is not provided
• The onDismiss prop is not provided

The submitLabel prop and the corresponding onSubmit prop should be provided to handle the user's acknowledgement and close the dialog.

Asynchronous actions

When triggering an action that may take some time, is can be useful for the user to remain on the modal until the action has completed.

You can set the isSubmitting prop to indicate that the modal is processing the action.

Content preview image

Images can be used to enhance the content of the dialog and are ideal for marketing content. Images will render full-bleed inside of a card (i.e. without padding between the image and the dialog container). Images will fill the width of the container while maintaining their aspect ratio.