Modal

Modals are used to request information or feedback from the user, confirm a decision, or less frequently to provide additional context about a function or feature.

Usage

When to use

• When requesting an urgent or immediate response from the user.
• As a confirmation when performing a destructive action or action that will impact other areas of the application.
• For non-frequent tasks that can be interacted with quickly.

When not to use

• When a user action is not immediately required.
• In place of an alert, consider Toast or Alert.
• For complex editing, long forms, and experiences with a high level of detail. In these cases, the task or function should exist at the page level.

Color

Neutral

Use Neutral for most Modal instances, such as when the outcome of the Modal’s function doesn’t change areas of the application that aren’t directly tied to the user’s current context.

Common examples include:

• Functions for creating, editing, or updating objects.
• Simple requests of information from the user.
• Quick confirmations of actions taken by the user.

Warning

Use Warning to indicate that the Modal’s action may impact a setting, item, or object. Warning Modals simultaneously alert of the potential impact while confirming the action.

Common examples include:

• Disabling or enabling an application-wide setting or feature.
• Archiving an item that can be recovered.
• Changing a setting that may require the user to re-authenticate or perform an action again.

Critical

Use Critical to indicate an irreversible destructive action that will impact other settings, items, or objects within the current feature or in other application areas.

Common examples include:

• Deleting an item or object that cannot be recovered.
• Modifying a setting that cannot be changed or reversed in the future.
• Alerting the user of unsaved changes that will be discarded.

Size

Width

We recommend using the medium size Modal for most scenarios, but use the size that best accounts for the complexity of the content and intended speed of interaction. We do not recommend resizing the Modal manually.

Height

The Modal should hug the body content and expand to a maximum height of 100% of the viewport height minus 16px from the edge. If the body content exceeds the maximum height of the viewport, scroll will be introduced within the Modal body, while the header and footer remain fixed.

Position

Modals should be positioned in the center of the viewport, paired with the overlay component, and on top of all parent page content (including the navigation).

Modal header

Title icon

The purpose and function of the Modal should not rely solely on an icon, instead the title should be explicit and pragmatic while the icon provides visual support.

With title icon

An icon paired with the title can help reinforce the purpose and function of the Modal while also drawing the eye to the header and title area. Icons can be used to communicate the severity and importance of interacting with a Modal and are especially useful in a warning or critical color Modal.

Without title icon

Tagline

A tagline helps the user maintain the context of the feature, function, or flow the Modal was triggered by. Since a Modal disables and obscures the parent page content, adding a tagline can help the user understand the relationship between the Modal and the parent page content. The tagline should directly reference the page, function, or feature title to reinforce the relationship of the Modal to the parent page content.

With tagline

With tagline and icon

Modal body

Modals can take on many different types of content, from text-based content to simple forms.

Modal footer

Most Modals should have a low to medium level of complexity and promote interaction with a simple “yes/no” or “ok/cancel”. If the complexity of the Modal breaks this pattern, consider moving the function performed by the Modal to the parent page.

Action patterns

One action

We recommend using the Primary Button when only one action is present in the Modal.

Two actions

We recommend using a ButtonSet (Primary Button followed by a Secondary Button) when two actions are present in the Modal.

Three actions

We recommend using a ButtonSet (Primary Button followed by a Secondary Button) plus a Tertiary Button or Standalone Link when three actions are present in the Modal. If a tertiary action is needed, it should not be grouped in the ButtonSet, as functionality should determine button grouping.

Common examples of tertiary actions include:

• Linking to external documentation.
• Linking to another related area or function within the application; best used to help the user better understand or collect the information needed to interact with the Modal.

Action content guidelines

• Modal actions should be concise and not written as sentences. Most of the time, one or two words are adequate for an action.
• We generally don’t recommend using icons on actions within Modals.
• Buttons in a Modal should follow the same content guidelines as the Button component.

Dismissal

The following actions will dismiss or close the Modal unless isDismissDisabled is set to true:

• Dismiss button in the Modal header
• Clicking outside the Modal on the overlay
• Hitting the escape (ESC) key on the keyboard
• A cancel or close button in the footer can also act as a way to dismiss the Modal, but doesn’t always function in the same way.

In addition to having proper ways for the user to dismiss a Modal, ensure the entry point for a Modal is straightforward enough that if a user accidentally dismisses it, the Modal can be easily triggered again.

Via dismiss button

The most common dismissal method for a Modal is via the dismiss button in the Modal header. This acts as an escape hatch for the user and helps prevent the user from getting stuck.

While we typically don’t recommend removing or hiding the dismiss button, it can be done to elevate the importance of the Modal and lower the possibility of accidental dismissal, in which case, a “cancel” button could be added as an escape hatch.

Via “cancel” button

While certain experiences may only call for a single action button, we recommend adding a “cancel” button as a more explicit method to close the Modal.

Depending on the information being requested, a secondary action that closes or cancels the model may not perform the same function as dismissing the Modal. For example, responding “no” to a “yes/no” question is not the same as dismissing the Modal, the latter of which does not submit a response.

Best practices for avoiding data loss

If a user attempts to dismiss a Modal that contains a partially filled form or other interactive elements, we recommend ensuring that the following criteria are met to promote a positive user experience:

• The default browser notification is being triggered calling attention to a potential misstep.
• Partially filled form data is persisted within the application to prevent duplicative work.

Browser support

The Modal component leverages the <dialog> element which is currently supported by all major browser vendors.

Page scroll

When a Modal is open, the rest of the page becomes inert. The page scrolling is also disabled by applying overflow: hidden to the <body> element, to make it clear to the user that the underlying elements are not interactive and to avoid confusion. Depending on users’ scroll bar settings, opening a Modal may cause slight layout shifts on the horizontal axis.

Positioning

As an overlaying component, the Hds::Modal is rendered on the top layer, meaning it is always placed on top of all other elements in the page.

Focus and focus trap

This component uses ember-focus-trap to prevent the focus from going outside the Modal and to dismiss the Modal when clicking outside the Modal. This Ember modifier requires at least one interactive element to be present within the Modal, which is by default achieved by the dismiss button in the header.

When a Modal is opened with the keyboard, the focus is automatically set to the first focusable element inside the Modal, which is the “Dismiss” button. The action of this button has no effect on the system, so focusing on it helps prevent users from accidentally confirming the Modal.

When the Modal has been closed, the browser automatically returns the focus to the element that initiated the opening. If that element doesn't exist anymore in the DOM (e.g., if the Modal is opened using an Interaction item in a Dropdown) the focus is returned to the <body> element. To avoid this side-effect (that comes with accessibility implications), it's possible to use the @returnFocusTo argument, where the consumer can provide the DOM id attribute of the element where the focus should be returned once the Modal is closed.

How to use this component

<Hds::Button
  @text="Open basic modal"
  @color="secondary"
  {{on "click" (fn this.activateModal "basicModalActive")}}
/>

{{#if this.basicModalActive}}
  <Hds::Modal
    id="basic-modal"
    @onClose={{fn this.deactivateModal "basicModalActive"}}
    as |M|
  >
    <M.Header>
      Modal title
    </M.Header>
    <M.Body>
      <p class="hds-typography-body-300 hds-foreground-primary">Modal content</p>
    </M.Body>
    <M.Footer as |F|>
      <Hds::Button type="button" @text="Confirm" {{on "click" F.close}} />
    </M.Footer>
  </Hds::Modal>
{{/if}}

Form within a Modal dialog

If a Modal dialog presents a form, the initial focus should be set on the first input, as the first focusable element in the form. This can be achieved by setting the autofocus property on the first form input.

The <form> element should be placed in the Hds::Modal::Body subcomponent. We also recommend to associate it to the submit button using the form attribute, as shown below.

When the Modal dialog contains information that might be lost on close, use a confirmation message before discarding it.

<Hds::Button
  @text="Open form modal"
  @color="secondary"
  {{on "click" (fn this.activateModal "formModalActive")}}
/>

{{#if this.formModalActive}}
  <Hds::Modal
    id="form-modal"
    @onClose={{fn this.deactivateModal "formModalActive"}}
    as |M|
  >
    <M.Header>
      Why do you want to leave the beta?
    </M.Header>
    <M.Body>
      <form id="leaving-beta-form" {{on "submit" (fn this.submitForm)}}>
        <Hds::Form::Select::Field autofocus @width="100%" as |F|>
          <F.Label>Select the primary reason</F.Label>
          <F.Options>
            <option></option>
          </F.Options>
        </Hds::Form::Select::Field>
        <Hds::Form::Textarea::Field @isOptional={{true}} as |F|>
          <F.Label>Your feedback</F.Label>
        </Hds::Form::Textarea::Field>
      </form>
    </M.Body>
    <M.Footer as |F|>
      <Hds::ButtonSet>
        <Hds::Button type="submit" form="leaving-beta-form" @text="Leave Beta" />
        <Hds::Button type="button" @text="Cancel" @color="secondary"
          {{on "click" F.close}}
        />
      </Hds::ButtonSet>
    </M.Footer>
  </Hds::Modal>
{{/if}}

Component API

Modal

Contextual components

[M].Header

The DialogPrimitive::Header component, yielded as contextual component.

[M].Body

The DialogPrimitive::Body component, yielded as contextual component.

[M].Footer

The DialogPrimitive::Footer component, yielded as contextual component.

Anatomy

Conformance rating

The Modal component is conformant when used as directed.

Focus and focus order

• When the modal is open, focus moves to the first interactive element within the modal and is trapped within the component.
• Since a Modal is a complex pattern that can contain any combination of nested components and content, nested elements must adhere to their individual accessibility criteria.

Focus order within a simple Modal

Given the Modal is triggered via a keyboard, the dismiss button is first in the focus order since there isn’t any content within the body that is eligible to receive focus.

Focus order within a complex Modal

If the Modal body contains interactive content, such as input fields, the first element should receive focus first regardless of how the Modal is triggered; either via a mouse click or via the keyboard. This behaviour should be implemented by setting the focus on the first element.

Applicable WCAG Success Criteria

This section is for reference only, some descriptions have been truncated for brevity. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

4.15.0

Updated

Aligned private class properties to follow a standardized notation

4.13.0

Updated

Added returnFocusTo argument to control where the browser focus is returned once the modal is closed

Fixed isDismissDisabled functionality

4.12.0

Updated

Fixed issue with box-sizing inheritance due to a all: unset CSS rule applied to the DialogPrimitive subcomponent

4.10.0

Updated

Modal.Header

Changed the HTML element wrapping the tagline and title from a <div> to a <h1>. If you have a heading HTML tag inside the header yield block, either remove it or change it to a <span>.

4.7.0

Deprecated

In this version, the Modal sub-components have been deprecated and replaced with the equivalent DialogPrimitive sub-components (shared also with the Flyout component). The deprecated Modal sub-components will be removed in the next major release.

To do the migration, if you use the <Hds::Modal::***> invocation:

If instead you use the (component hds/modal/***):

In the refactoring, we have been able to maintain existing CSS class names to avoid breaking current tests and CSS overrides in consumers' codebases.