Modal

<bolt-button onclick="window.contentModal.openModal()">
  Content modal
</bolt-button>

<bolt-modal
  id="contentModal"
  heading="Content title"
  primarybutton="Close"
>
  <p>
    Content body copy is used for body copy. Lorem ipsum dolor set amet,
    consectetur adipici elit, sed do eiusmod tempor.
  </p>
</bolt-modal>

<bolt-button onclick="window.confirmModal.openModal()">
  Confirmation modal
</bolt-button>

<bolt-modal
  id="confirmModal"
  heading="Confirmation statement"
  primarybutton="OK"
  type="confirm"
>
  <p>
    Confirmative message that notifies users that a process has been successfully completed.
  </p>
</bolt-modal>

<bolt-button onclick="window.errorModal.openModal()">
  Error modal
</bolt-button>

<bolt-modal
  id="errorModal"
  heading="Error statement"
  primarybutton="OK"
  type="error"
>
  <p>
    Error message that explains the nature of a problem and what users can
    do to solve it.
  </p>
</bolt-modal>

<bolt-button onclick="window.questionModal.openModal()">
  Question modal
</bolt-button>

<bolt-modal
  id="questionModal"
  heading="Question statement?"
  primarybutton="Default answer"
  secondarybutton="Other answer"
  type="question"
>
  <p>
    Question with two answers, asking if users would like to do one thing
    versus another.
  </p>
</bolt-modal>

<bolt-button onclick="window.infoModal.openModal()">
  Information modal
</bolt-button>

<bolt-modal
  id="infoModal"
  heading="Information statement"
  primarybutton="OK"
  type="info"
>
  <p>
    Informative message that helps users understand how current conditions
    affect what they can and cannot do.
  </p>
</bolt-modal>

<bolt-button onclick="window.warningModal.openModal()">
  Warning modal
</bolt-button>

<bolt-modal
  id="warningModal"
  heading="Warning statement"
  primarybutton="OK"
  type="warning"
>
  <p>
    Warning message that lets users know something is not working and
    requires their attention.
  </p>
</bolt-modal>

To accommodate long content, a modal's main area can be scrolled vertically. The button(s) at the bottom of the modal remain visible at all times.

<bolt-button onclick="window.longModal.openModal()">
  Long modal
</bolt-button>

<bolt-modal
  id="longModal"
  heading="Content title"
  primarybutton="OK"
  type="info"
>
  <p>Lorem ipsum dolor sit amet...</p>
  <p>Egestas sed tempus urna et pharetra...</p>
  <p>Consequat nisl vel pretium lectus...</p>
  <!-- ... -->
</bolt-modal>

For more granular control of the bolt-button elements within the modal, the button bar slot allows direct application of custom attributes and events. See Bolt's button bar documentation for more information about configuring the button bar component within this slot.

<bolt-button onclick="window.customButtonModal.openModal()">
  Custom buttons
</bolt-button>

<bolt-modal
  id="customButtonModal"
  heading="Content title"
>
  <p>Lorem ipsum dolor sit amet...</p>
  <!-- ... -->

  <bolt-button-bar slot="modal-button-bar">
    <bolt-button
      slot="forward"
      type="solid"
      onclick="window.customButtonModal.closeModal()"
    >Close</bolt-button>

    <bolt-button
      slot="back"
      onclick="window.customButtonModal.closeModal()"
    >Do something</bolt-button>

    <bolt-button
      slot="cancel"
      onclick="window.customButtonModal.closeModal()"
    >Do another thing</bolt-button>
  </bolt-button-bar>
</bolt-modal>

The bolt-modal web component displays a message within a full-page overlay.

The component supports the following attributes:

• type: optional. content (default), confirm, error, question, info, or warning
  • For message modals, determines which icon is used.
  • For content modals, omit or use type="content" (default).
• heading: Sets the heading text to be displayed at the top of the modal.
• Buttons located at the bottom of the modal.
  • primarybutton: Sets the text to be displayed on the default button. Used for the preliminary or main action.
  • secondarybutton: (optional) Sets the text to be displayed on the supporting button. Used for a supporting or auxillary action.
  • tertiarybutton: (optional) Sets the text to be displayed on the button displayed on far left. Used for an additional action.
• open: (Boolean) property that serves as an alternate to calling the openModal() function to open a modal. Setting to true, or its presence, will open the modal. Setting to false, or its absence, will close the modal.

Slot: modal-button-bar: (optional) Add custom buttons using a bolt-button-bar

• Custom buttons do not close the modal by default.
• Note: Do not use the button properties primarybutton, secondarybutton, nor tertiarybutton on the modal when adding custom buttons.
• Custom buttons do not emit bolt-modal-primary-button-click, bolt-modal-secondary-button-click, nor bolt-modal-tertiary-button-click events.

The element exposes the following public Javascript APIs:

• openModal(): Opens the bolt-modal that the function is called from.
• closeModal(): Closes the bolt-modal that the function is called from.

The component emits the following events:

• bolt-modal-open: emitted when opening the modal.
• bolt-modal-close: (cancelable) emitted when closing the modal.
• bolt-modal-primary-button-click: (cancelable) emitted when the default button on the modal is clicked.
• bolt-modal-secondary-button-click: (cancelable) emitted when the secondary button on the modal is clicked (if present).
• bolt-modal-tertiary-button-click: (cancelable) emitted when the tertiary button on the modal is clicked (if present).

A handler for each of these events can be added via addEventListener() or in Angular via the inline syntax:

<bolt-modal
  (bolt-modal-primary-button-click)="submitModalForm()"
  primarybutton="Submit"
  secondarybutton="Option"
  tertiarybutton="Cancel"
  id="modalId"
  title="Content title"
></bolt-modal>

• Modals should be used sparingly as they are disruptive, forcing users to stop their current task and focus on the Modal's content.
• Keep a Modal's purpose clear, with a descriptive title and concise, minimal content.
• Simplify the number of interactions in a Modal dialog by removing unnecessary elements or content.
• Prefer a single-column layout for Modals.
• A semi-opaque curtain is displayed over the entirety of the screen between a Modal and the rest of the page's content to prevent users from clicking screen elements below it.
• Background content should not scroll while a Modal is displayed.

• Modals require action to be taken inside them, clicking outside the Modal does not dismiss the Modal.
• Modals must have at least one Button, typically a Solid Button, that is the most common or the preferred action.
• When a Modal is displayed, there may be only one Solid Button. It should be on the far right (horizontal button layout) or top (vertical button layout).
  • The Solid Button is focused by default and is typically the least destructive action.
• Outline Buttons inside a message Modal are optional and used for less important or more destructive actions (such as cancel).
  • If the Modal presents a question, there should be at least 1 Outline Button along with the Solid Button.
• While a Modal is displayed, users of devices with physical keyboards can use keystrokes to:
  • press the Enter key to select the Solid Button.
  • change focus between screen components inside the Modal.
• After a Modal is closed, focus returns to the same screen element that triggered its display.

Modals come in 2 varieties: message and content Modals.

• Message Modals are designed to interrupt users before they can continue a task.
• Message Modals do not have a dismiss (X) Button as users should not be able to dismiss a message Modal before responding to its question.
• If a user needs to:
  1. answer a decisive, mutually exclusive question, use a Question Modal.
  2. read a critical error message (which explains a problem and what they can do to solve it), use an Error Modal.
  3. read an informative message that helps them understand how current conditions affect what they can and cannot do, use an Information Modal.
  4. read a message that lets them know that a process has been successfully completed, use a Confirmation Modal.
  5. read an important warning message that lets them know something is not working, use a Warning Modal.

• Content Modals are used to display content that cannot be displayed on a page or new browser window/tab.

• Low-level destruction is defined as a user-initiated destructive action where the likelihood of losing data is either of minimal or no concern.
• This pattern allows a user the ability to confirm an action with only a Button click.
• Example 1: A user presses the "Log out" Button. A Modal appears asking if they are sure that they want to log out. This is minimally destructive because:
  • continuing this task will take the user out of their current context (in this case, being logged in).
  • there will be no data lost by logging out.
  • the user can easily recover from an incorrect answer by logging back in.
• Example 2: A user clicks a Link that results in navigating away from a page while they are filling out a form that has not yet been submitted. A Modal appears asking if they are sure that they want to navigate away from the page because the data entered will be lost. This is minimally destructive because:
  • continuing this task will take the user out of their current context (in this case, being in the middle of a process).
  • the data is not already committed to the database.
  • the user can easily recover from an incorrect answer by filling out the form again.

• Medium-level destruction is defined as a user-initiated destructive action where data is being removed from a system or database but can be easily re-entered.
• This pattern adds a required Checkbox to the same low-level pattern. The intention here is for the user to acknowledge twice that they understand the consequences of proceeding with their action: once via checking the box, then also by pressing a Button. If the Checkbox is not checked, normal error validation should occur.
• Example: A user clicks a Link to remove a beneficiary from their account. A Modal appears asking if they are sure that they want to continue with this action. This Modal contains a Checkbox with a message giving explicit acknowledgement that by continuing, their beneficiary will immediately be removed. In this case, there is deletion of data from the system, but the user can easily re-enter their data via the "Add beneficiary" process.

• High-level destruction is defined as a user-initiated destructive action where data is being removed from a system or database and is not recoverable or easily re-entered.
• This pattern replaces the Checkbox from the medium-level process with a Text field requiring the user to type specific text to proceed. The intention is that the user is actively engaged in the destruction process and its confirmation. If the entered text does match exactly what is required, normal error validation should occur.
• Example A: A user clicks a link to delete their account. A Modal dialog appears asking if they are sure that they want to continue with this action. This Modal contains a Text field with a label reading: 'Type "Delete account" in the field below to continue.' In this case, there is deletion of data from the system that is permanent and unrecoverable.
• Example B: A user clicks a link to remove a beneficiary from their account AND Nationwide is not the beneficiary keeper of record. There is no way to add a new beneficiary online. This Modal contains a Text field with a label reading: 'Type "Delete beneficiary" in the field below to continue.' In this case, there is deletion of data from the system that is permanent, unrecoverable, and must be re-submitted via an external process.

• Use Modals to reveal critical information without losing context.
• Use Modals to alert a user that their action would result in data loss. For more specific guidance, see destructive Modal guidance.

• Avoid Modals when content can be displayed inline.
• Avoid using Modals for displaying non-critical information that does not need to interrupt a workflow.
• Avoid complex decision-making that requires access to sources of information unavailable in the Modal.
• Avoid Modals if you need to deliver a brief, auto-expiring element.

• Consider alternative patterns such as non-modal dialogs or undo patterns for continuing the system-user conversation while keeping the user focused on their task.
• Avoid Modals for error notifications; use Notification instead.
• If there is non-essential content related to the page that is less than 560 characters, use Contextual help. If content exceeds 560 characters, a Modal may be used.

• Modal headings use sentence case and do not include a period or colon.
• Modal messages use sentence case, include a period, and should be clear and concise.
• Be specific and inform users about the consequence of their action.
• Write in such a way that that the action clearly defines the outcome.
• When writing for destructive actions, make choices mutually exclusive.

• When a Modal opens:
  • The screen reader should announce Modal heading title, dialog due to the role="dialog" attribute applied to the Modal container. This attribute informs assistive technologies that the content is a dialog box, helping users understand the context of the interaction.
  • Focus should automatically be directed to the title within the Modal.
• Navigating within the Modal:
  • Tab and Shift+Tab should move focus forward and backward (respectively) through interactive elements inside the Modal.
  • Up and down arrow keys should move focus backward and forward to an adjacent line or element within the content.
  • Focus should be trapped within the Modal. If the user tabs past the last focusable element, focus should loop back to the first focusable element, and vice versa.
• Closing the Modal:
  • Pressing Esc should close the Modal and return focus to the trigger element that opened the Modal.
  • The close button inside the Modal should be able to be activated with the Enter or Space key.

• When a Modal is open, screen readers read content differently on different browsers:
  • JAWS + Chrome : announce dialog title.
  • JAWS + Edge : announce dialog title.
  • NVDA + Chrome : announce dialog title 2x.
  • NVDA + Edge : announce dialog title 2x.

• In order for screenreaders to read the Modal's content, you must wrap content in an HTML tag. For example a <p> tag.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.