Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,16 @@ section: components
related: ['Button']
---

import '../components.css';

import CheckIcon from '@patternfly/react-icons/dist/esm/icons/check-icon';
import TimesIcon from '@patternfly/react-icons/dist/esm/icons/times-icon';

## Elements

<img src="./img/modal-call-outs.png" alt="An example of a modal in context with call outs to highlight each listed element" width="756"/>
<div class="ws-docs-content-img">
![Elements of a modal.](./img/modal-elements.svg)
</div>

1. **Backdrop**
2. **Modal box**
Expand Down Expand Up @@ -55,13 +59,17 @@ Use a confirmation dialog to validate user decisions and communicate their conse

#### Confirm a non-destructive action

<img src="./img/non-destructive-confirmation-dialog.png" alt="A side-by-side comparison of unsuccessful and successful confirmaton dialogs for leaving a page without saving. The successful dialog explains the consequence of this action: All unsaved informaton will be lost" />
<div class="ws-docs-content-img" style="min-width:100%">
![A side-by-side comparison of unsuccessful and successful confirmaton dialogs for leaving a page without saving.](./img/modal-non-destructive.svg)
</div>

When confirming a non-destructive action, provide specific context about what will happen once a user confirms it.

#### Confirm a destructive action

<img src="./img/destructive-confirmation-dialog.png" alt="A side-by-side comparison of unsuccessful and successful destructive confirmaton dialogs for deleting a record. The successful dialog explains the consequence of deleting this record: Record name, location, and notes will be lost" />
<div class="ws-docs-content-img" style="min-width:100%">
![A side-by-side comparison of unsuccessful and successful destructive confirmaton dialogs.](./img/modal-destructive.svg)
</div>

Use a [primary button](/components/button/design-guidelines#primary-button) to confirm a destructive action. If the action carries serious consequences, then use a [danger button](/components/button/design-guidelines#danger-button) instead.

Expand All @@ -71,21 +79,27 @@ If a destructive action has serious consequences, consider adding an additional

When a text input field is added to a confirmation dialog, the danger button will only become enabled once a user enters the entire word or phrase.

<img src="./img/destructive-confirmation-dialog-steps.png" alt="A multi-step destructive confirmation dialog's button activates only after a user types DELETE into the input field" />
<div class="ws-docs-content-img" style="min-width:100%">
![Example of a destructive confirmation dialog that requires an input field be filled before continuing.](./img/modal-destructive-text-input.svg)
</div>

### Edit dialogs

Use an edit dialog for managing assets. Edit dialogs contain multiple actions which can include, but are not limited to, saving your changes or deleting the asset. The primary action in the dialog should use a primary button, the secondary should use a secondary button, and the cancel button should remain a link button.

For example, and edit dialogue might contain a "Save" button as the primary action, and a "Delete" button as a secondary action. If the secondary action is destructive, the button should be styled as a [secondary danger button](/components/button/#variant-examples). Additionally, it should be aligned to the right-side of the modal, directly across from the primary action and cancel buttons.

<img src="./img/secondary-destructive-action.png" alt="An edit dialogs with three action buttons: save, cancel and delete" width="500"/>
<div class="ws-docs-content-img">
![Example of an edit dialog.](./img/modal-edit-dialog.svg)
</div>

When using destructive actions, ensure that the user is informed about the consequences of taking this action. Review the general guidelines for [danger button](/components/button/design-guidelines#danger-button) and destructive actions for additional guidance.

### Error dialogs

<img src="./img/error-dialog.png" alt="An example of a successful error dialog, with and without an optional error icon" />
<div class="ws-docs-content-img" style="min-width:100%">
![Example of an error dialog, with and without an optional error icon.](./img/modal-error-dialog.svg)
</div>

Use an error dialog to inform users of problems that interrupt normal or expected behavior. Briefly contextualize the problem and why it happened, then provide actionable steps toward a solution.

Expand All @@ -95,7 +109,9 @@ Error dialogs may use an error icon for visual emphasis.

### Passive dialogs

<img src="./img/passive-dialog.png" alt="An example of a successful passive dialog, with and without an optional warning icon" />
<div class="ws-docs-content-img" style="min-width:100%">
![Example of a passive dialog, with and without an optional warning icon.](./img/modal-passive-dialog.svg)
</div>

Use a passive dialog to communicate critical and immediately relevant information like the status of an application or an action’s result. Passive dialog content should require or lead to user action.

Expand All @@ -109,15 +125,19 @@ Users may need to provide additional input to complete an action. To accomplish

### Modals with help

<img src="./img/modal-with-help.png" alt="A modal with help uses a help icon to open a help popover when clicked" />
<div class="ws-docs-content-img" style="min-width:100%">
![Example of a modal with a help icon and popover.](./img/modal-with-help.svg)
</div>

Use a [modal with help](/components/modal#with-help) to make complex tasks easier to understand within a modal. If needed, link to further documentation in the help popover.

Help popovers at the modal level explain and provide documentation for an entire task. Only place a help icon at the modal level if its information applies to all content in the modal. If the information you'd like to include in a help popover is specific to a particular input, place the help icon at that input level instead.

## Spacing

<img src="./img/modal-basic.png" alt="A basic modal with 24px spacers between the modal box and content, and 16px spacers between the headline and content area, and between each button" width="487" />
<div class="ws-docs-content-img">
![Example of the spacing used in a basic modal.](./img/modal-spacing.svg)
</div>

Basic modals use a primary spacing of 24px to separate:

Expand All @@ -134,15 +154,19 @@ A modal can be aligned at the center or top of a page.

A [center-aligned modal](/components/modal/html-demos/basic/) appears horizontally and vertically centered on a page, and should be used by default for most use cases.

<img src="./img/center-aligned-modal.png" alt="A modal pictured in center alignment on a page" />
<div class="ws-docs-content-img">
![Example of a modal in center alignment on a page.](./img/modal-center.svg)
</div>

### Top-aligned modal

A [top-aligned modal](/components/modal/html-demos/top-aligned/) appears horizontally and vertically centered at the top of a page.

Use a top-aligned modal when your modal contains expanding content or when you'd like to keep content behind the modal visible to the user.

<img src="./img/top-aligned-modal.png" alt="A modal pictured in top alignment on a page" />
<div class="ws-docs-content-img">
![Example of a modal in top alignment on a page.](./img/modal-top.svg)
</div>


## Content considerations
Expand Down