Modal

Overview#

  • A Modal is a child overlay that prevents users from interacting with the rest of the parent application until a specific action is taken. It should be used thoughtfully and sparingly.
  • Modals are focused. They require a user action before they can be completed.
ComponentPatternUser action
MessageLow priorityOptional: Messages disappear automatically
AlertProminent, medium priorityOptional: Alerts remain until dismissed by the user, or if the state that caused the alert is resolved
ModalHighest priorityRequired: Modals block app usage until the user performs an action or exits the modal (if available)

Use when#

  • A user must complete one or multiple actions before they can continue with the main workflow.
  • A user must be notified about information that is critical to the flow.
  • A user must be notified about an irreversible decision that will result in the loss of information (overwriting/saving).
  • A complex flow requires that information be fragmented into one or multiple steps.
  • A user should be asked for information that, when provided, could significantly reduce the users' work or effort.

See modal types below for more information.

Don't use when#

  • The action does not require immediate attention from the user.
  • The result of the action does not justify interrupting the user.
  • The user must make complex decisions that may require additional sources of information unavailable in the modal.
  • You are presenting non-essential information that is not related to the current user flow.
  • The user is already in a focused modal state (stacking modals). With the exception of making a selection via dropdown.

See modal types below for more information.

Visual Style#

  • Appears on top of all content.

See modal types below for more information.

Editorial#

  • A modal’s purpose should be communicated by its title and button text.
  • Titles should contain a brief, verb + noun question or statement. (Example: Discard unsaved changes?)
  • Titles should avoid apologies (“Sorry for the interruption”), alarm (“Warning!”), or ambiguity (“Are you sure?”)
  • Primary and secondary button actions should be clear and action focused. Use button action nomenclature here.
  • Description text should be clear, focused, and is only required if the purpose of the modal can not be communicated effectively in the title.

See modal types below for more information.

Behaviour#

  • A modal state moves the system into a focused mode, requiring user interaction.
  • This state disables main content until the user explicitly interacts with a modal action.
  • Do not close when clicking outside the modal in disabled space.
  • Do not use more than two action buttons in the modal (primary and secondary).

See modal types below for more information.

Accessibility#

  • Users can tab or shift tab between actions.

Modals come in three types.#

The information above will apply to all modals plus the specific modal type content below:

Confirmation Modal#

This modal interrupts a user with urgent information, details, and actions that require confirmation.

Use when#

  • A user must be interrupted with urgent information, details, or actions.
  • A user must select between two important options (action buttons).

Don't use when#

  • You need to display complex forms or large amounts of information.

Visual Style#

  • Use the appropriate modal-type icon to the left of the heading (warning).
  • Display as one single content space with no horizontal lines dividing content.
  • Should take up no more than 50% of the visible screen.
  • Should be center aligned horizontally and vertically, showing content below on all four sides of the modal.
  • Should be placed on top of content, over a disabled, transparent background.
  • Action buttons should be placed side-by-side on the bottom right and follow button guidelines found here.

Behaviour#

  • Dismiss with an action button.
  • Do not use the "X" cancel icon.
  • The modal should not contain scrollable content.

Accessibility#

  • User can exit the modal by using the "ESC" key on their keyboard.

Default Modal#

This modal is a container for simple, selection-based tasks that are required within a flow. The content space of this modal is flexible and will be further defined as additional use cases are discovered.

modal-2-default

Use when#

  • A user must select from a list of items that take immediate effect when selected.
  • One or two simple selections must be made within a flow.

Don't use when#

  • A user must select between two important options. Use a Confirmation Modal instead.
  • A user is tasked with completing a form or a large number of subsequent selections.

Visual Style#

  • Should have a defined header, footer and content spaces.
  • Should take up no more than 50% of the visible screen.
  • Should be center aligned horizontally and vertically, showing content below on all four sides of the modal.
  • Should be placed on top of content, with a disabled, transparent background.
  • Action buttons should be placed side-by-side in the footer and follow button guidelines found here.

Behaviour#

  • This modal can be dismissed with an action button or cancelled with a "X" icon.
  • The modal may contain scrollable content.
  • The header and the footer should be fixed and should not scroll with content.
  • If a keyboard or selection dialog is required, it should not obscure modal content.

Accessibility#

  • User can exit the modal by using the "ESC" key on their keyboard.

Full Page Modal#

This modal fills the entire screen and contains actions that require a series of tasks to complete. They can be used to progressively disclose information and break complex screens into multiple steps. Examples include creating a customer or searching for a product within a flow.

Mobile full screen modals are not included in this documentation.

modal-3-full-page

Use when#

  • A user must complete a focused task that requires a series of steps or actions to complete.
  • A user must complete a complex form.

Don't use when#

  • A user must select between two important options. Use a Confirmation Modal instead.
  • A user is required to select from a single set of values to apply to the current flow.

Visual Style#

  • Should have a defined header and content spaces.
  • Should take up 100% of the available content space (spaces not including the primary header and navigation header in RQ & Hub).
  • Action buttons should be placed side-by-side in the header and follow page header guidelines here.

Editorial#

Behaviour#

  • A series of actions which pertain to a focused flow (such as adding a customer or editing a product).
  • Components within full screen modals may open additional modals.
  • If no changes have been made, the full-screen modal closes and no discard confirmation modal is required.
  • If the user has made changes, the user will be prompted to confirm the discard action with a confirmation modal.

Accessibility#

  • The new page should include the appropriate title tags.

Related components#

  • To present a small amount of content or a menu of actions in a non-blocking overlay, use the popconfirm component.
  • To communicate a change or condition that needs the user’s attention within the context of a page use the alert component.
  • To communicate low priority, at-a-glance feedback after the outcome of an action, use the message component.
Last updated on by Larissa Hsia