Modal

Examples

View in Pajamas UI Kit →

Structure

1. Dialog: Modal dialog container.
2. Title: A short question or descriptive phrase that conveys an overview of the purpose.
3. Dismissal: Icon to dismiss the modal.
4. Message: Text content indicating the purpose and potential next steps.
5. Actions (optional): Buttons used to provide explicit action(s) the user can take to either remedy the modal or continue with a task.
6. Backdrop: Transparent overlay that covers the page content.

Guidelines

When to use

• Serve as a single purpose dedicated to completing the user's task.
• Reveal critical information without losing context.
• Require a user response from the system.
• Confirm a non-revertible destructive action.

When not to use

• When content can be displayed inline. Utilize elements such as popovers, accordions, or drawers to present additional information while allowing the user to maintain focus on the page.
• If you need to deliver a brief, auto-expiring element for a user to consume while staying focused on their task, use a toast instead.
• For a significant amount of content, take the user to a different page to utilize space a modal can‘t provide.
• Consider alternative patterns such as non-modal dialogs or undo patterns to continue the system-user conversation while keeping the user focused on their task.

Inline alternative

For simple edits, consider inline editing:

Clicking the "edit" button places a user in an "edit mode" for this row, which utilizes form inputs to edit text fields:

Sizes

• Small: A small modal is used for simple tasks with little content.
• Medium (default): A medium modal is used for most use cases.
• Large: A large modal is used for wide content that might use tabs or a table or otherwise benefit from a wider container.

Behavior

• Width scales down responsively when the page is narrower than the modal's max width.
• The height of the modal is determined by the content.
  • When modal content extends below the viewport, the viewport remains scrollable.
  • If modal content exceeds the height of the viewport and impedes a user’s ability to maintain context or see important actions, the content within the modal can be made scrollable. However, this should be avoided, if possible, because doing so impacts the ability for dropdowns and other popups (tooltips and popovers) to extend outside the boundary of the modal when necessary and to reposition as needed depending on available space.
• On small screens where content requires scrolling, consider opening the content in a new page instead.
• Focus should be placed on the modal title (read the accessibility notes for details).
• Keyboard focus is contained in the modal while it remains open.
• A modal can be dismissed by:
  • Clicking on the Close button within it.
  • Clicking on a Cancel button (or similar) within it.
  • The Esc key being pressed.
  • Clicking outside of it.
• When dismissed, focus returns to the referring control.

Content

• The header is either a question, a descriptive phrase, or title. The header also contains the close icon in every instance.
• The content in the body should never be ambiguous and unclear. Strive to be as concise as possible and provide the user with specific information in regards to their task. Do not ask a vague question or pose a vague statement. Instead, explain what you are asking the user to do by using UI text that's straightforward and easy to understand.
• When a modal is triggered in contexts where multiple items may be visible simultaneously, such as side-by-side panels, explicitly identify the item being acted on in the messaging. For example, prefer "Are you sure you want to delete the Q4 Planning epic?" over a generic "Are you sure you want to delete the epic?" to avoid ambiguity about what the action applies to.
• There should be no more than 3 actions and no fewer than 1. Actions should always be located within an action bar at the bottom of the modal. Button order and positioning should follow our guidelines for buttons.
• When labeling your actions, let the user know what will happen for each possible decision you are affording to them and be specific. For example, when asking the user to set their status, use "Set status" and "Remove status" instead of simply, "Save" and "Delete".
• There should always be multiple ways to close/dismiss this type of modal, including allowing the user to click outside of the modal area or use the escape key. This is important as some modals can be tall and we want to avoid making the user scroll up to close a modal.
• Follow the high severity destructive action guidance when the action is destructive or difficult to recover from.

Placement

• Opens on top of all other content with a transparent backdrop behind it.
• Top-aligned at the extra-small (xs) viewport size and otherwise vertically centered in the viewport.
• Horizontally centered in the viewport.

Accessibility

• A modal uses role="dialog" to indicate that it's a descendant of the main window.
• Focusing on a button or form element within can move a user past important contextual information or even scroll the start of the modal content out of view — it's also inconsistent from modal to modal. Therefore, it's recommended to initially place focus on the modal title and reference it by using the aria-labelledby attribute on the dialog. If there's no content before a control, except for the title, then focus can be placed on the control.
• A modal must be labeled with aria-label or aria-labelledby.
• See the WAI-ARIA Dialog (Modal) documentation for more details.

Code reference

VModel

You can use the v-model directive to control the modal’s visibility. The v-model directive interfaces with the visible property and the @change event.

Deprecation Warning

We are deprecating the modal-ok and modal-cancel slots. We are also changing the way the modal-footer slot content is populated. This is in order to align this component with the design system.

The modal-footer slot should only be populated via props: action-primary, action-secondary and action-cancel. These props allow you to handle how a primary, secondary and cancel button will behave in the modals footer. The props receive an object as such:

{
  text: 'Save Changes',
  attributes: {
    variant: 'confirm',
    disabled: this.someState,
    class: 'some-class',
    ...
  }
}

GlModal

Reference

• Making Modal Windows Better For Everyone, again...
• The current state of modal dialog accessibility
• What we learned from user testing of accessible client-side routing techniques with Fable Tech Labs
• Modal & Nonmodal Dialogs: When (& When Not) to Use Them