Modals are UI elements that interrupt the current page or task to focus the user's attention on a specific action, decision, or piece of information.

Components design versions:

  • Modal dialog v1.0.0
  • Fullscreen dialog v1.0.0

Note

You can find the OUDS design guidelines here: modal dialog guidelines, fullscreen dialog guidelines.

Overview

Component types

  • Modal dialog is a temporary, surface-like UI element that interrupts the current page or task to focus the user's attention on a specific action, decision, or piece of information.
  • Fullscreen dialog is a UI element that covers the entire viewport, interrupting the current page or task to focus the user's attention on a specific action, decision, or piece of information.

Approach

Modal dialog and fullscreen dialog use the same native <dialog> element with the .modal-base class. Either use .modal-dialog for a standard modal dialog or .modal-fullscreen-dialog for a fullscreen modal. The internal structure uses:

  • .modal-header for the header, it contains a .modal-title element for the main title.
  • .modal-body for the main content of the modal, it can contain a .modal-footer or not if using sticky actions.
  • .modal-footer for the action buttons for the modal.

The common variants are shared between modal dialog and fullscreen dialog, modal dialog has specific variants and sizes.

As this component relies on the native <dialog> element we encourage you to read the MDN documentation on the <dialog> element.

Heads up!

Interactivity

In this documentation we rely on invoker commands to trigger the opening, closing and light-dismissing of modals but you can also use JavaScript. Note that some browsers require a polyfill for full invoker commands compatibility.

Accessibility

As we use the native <dialog> element, we benefit from built-in accessibility features such as keyboard navigation, focus management, and screen reader support.

Some things to keep in mind while using modals include:

  • Ensure that the dialog has a meaningful and descriptive title, use the [aria-labelledby] attribute to reference the title element.
  • Choose the most appropriate initial focus when the dialog opens. By default, focus moves to the first focusable element; use [autofocus] when another element, such as the close button or an input, should receive focus.
  • Always provide an explicit and accessible way to close the dialog, such as a close, cancel, or confirmation button. Modal dialogs should also preserve the default Esc key behavior.
  • Open modal dialogs with showModal() or the show-modal invoker command so that the rest of the page is made inert and the dialog is exposed with modal semantics.
  • Adapt the title level to the context of the page, ensuring proper heading hierarchy.
  • Do not add [tabindex] to the <dialog> element.

Note

Read the MDN accessibility guidance for the <dialog> element for more information.

A modal dialog is a temporary, surface-like UI element that interrupts the current page or task to focus the user's attention on a specific action, decision, or piece of information.

The modal dialog appears over a backdrop that visually separates it from the underlying content and blocks interaction with that content.

See the approach section to get an overview of the modal dialog structure and classes.

<dialog id="modalDialog" class="modal-base modal-dialog" aria-labelledby="modalDialogTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogTitle" class="modal-title">Title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialog" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialog" command="close" autofocus>Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialog" command="show-modal">
  Open modal dialog
</button>
html

Variants

Fixed height

Add .modal-fixed-height to the <dialog class="modal-dialog"> to use the fixed height option. This variant can be used to define a fixed-height modal dialog for multi-step flows or content with a consistent layout. The modal dialog will use the maximum height available which depends on the modal size.

<dialog id="modalDialogFixedHeight" class="modal-base modal-dialog modal-fixed-height" aria-labelledby="modalDialogFixedHeightTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogFixedHeightTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogFixedHeight" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <p>On then sake home is am leaf. Of suspicion do departure at extremely he believing. Do know said mind do rent they oh hope of. General enquire picture letters garrets on offices of no on. Say one hearing between excited evening all inhabit thought you. Style begin mr heard by in music tried do. To unreserved projection no introduced invitation.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogFixedHeight" command="close">Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default m-xsmall" commandfor="modalDialogFixedHeight" command="show-modal">
  Open fixed height modal
</button>

<dialog id="modalDialogSmallFixedHeight" class="modal-base modal-dialog modal-small modal-fixed-height" aria-labelledby="modalDialogSmallFixedHeightTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogSmallFixedHeightTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogSmallFixedHeight" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogSmallFixedHeight" command="close">Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogSmallFixedHeight" command="show-modal">
  Open small fixed height modal
</button>
html

Non-blurred backdrop

By default the modal dialog backdrop is blurred to visually separate the modal from the underlying content. You can disable this effect by adding the .modal-non-blurred class to the modal dialog.

<dialog id="modalDialogNonBlurred" class="modal-base modal-dialog modal-non-blurred" aria-labelledby="modalDialogNonBlurredTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogNonBlurredTitle" class="modal-title">Title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogNonBlurred" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogNonBlurred" command="close">Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogNonBlurred" command="show-modal">
  Open modal without blurred backdrop
</button>
html

Sizes

Add .modal-small to switch to a small modal dialog. Use it when the dialog requires less space and the user can complete the task with minimal information or interaction.

<dialog id="modalDialogSmall" class="modal-base modal-dialog modal-small" aria-labelledby="modalDialogSmallTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogSmallTitle" class="modal-title">Small modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogSmall" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogSmall" command="close">Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogSmall" command="show-modal">
  Open small modal
</button>
html

Fullscreen dialog

A fullscreen dialog is a UI element that covers the entire viewport, interrupting the current page or task to focus the user's attention on a specific action, decision, or piece of information.

The fullscreen dialog layout mirrors the structure and behavior of a standard page and lacks a backdrop, making it ideal for complex tasks or content needing more space and interaction.

Fullscreen dialog uses the same native <dialog> element and internal structure as modal dialog, use .modal-fullscreen-dialog on <dialog> to make it a fullscreen dialog. See the approach section to get an overview of the fullscreen dialog structure and classes.

Only the common variants are available for this kind of modal.

<dialog id="demoFullscreenDialog" class="modal-base modal-fullscreen-dialog" aria-labelledby="demoFullscreenDialogTitle" closedby="any">
  <div class="modal-header">
    <h3 id="demoFullscreenDialogTitle" class="modal-title">Fullscreen dialog title</h3>
    <button type="button" class="btn btn-close" commandfor="demoFullscreenDialog" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual.</p>
    <p>On then sake home is am leaf. Of suspicion do departure at extremely he believing. Do know said mind do rent they oh hope of. General enquire picture letters garrets on offices of no on.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="demoFullscreenDialog" command="close">Confirm</button>
      <button type="button" class="btn btn-default" commandfor="demoFullscreenDialog" command="close">Cancel</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="demoFullscreenDialog" command="show-modal">
  Open fullscreen dialog
</button>
html

Using the grid

Use the OUDS Web grid system within a modal by adding .container-fluid and .container-max-width on .modal-header, .modal-body, and, if using sticky actions, .modal-footer. Then, use the normal grid system classes as you would anywhere else.

Note

In this example the .col-* classes are highlighted with a background color, as a result their padding is visible and it seems the alignment is off. In reality their content are properly aligned within the grid system.

<dialog id="demoFullscreenDialogGrid" class="modal-base modal-fullscreen-dialog" aria-labelledby="demoFullscreenDialogGridTitle" closedby="any">
  <div class="modal-header container-fluid container-max-width">
    <h3 id="demoFullscreenDialogGridTitle" class="modal-title">Fullscreen dialog title</h3>
    <button type="button" class="btn btn-close" commandfor="demoFullscreenDialogGrid" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body container-fluid container-max-width">
    <div class="row">
      <div class="col-md-4">.col-md-4</div>
      <div class="col-md-4 ms-auto">.col-md-4 .ms-auto</div>
    </div>
    <div class="row">
      <div class="col-md-3 ms-auto">.col-md-3 .ms-auto</div>
      <div class="col-md-2 ms-auto">.col-md-2 .ms-auto</div>
    </div>
    <div class="row">
      <div class="col-md-6 ms-auto">.col-md-6 .ms-auto</div>
    </div>
    <div class="row">
      <div class="col-sm-9">
        Level 1: .col-sm-9
        <div class="row">
          <div class="col-8 col-sm-6">
            Level 2: .col-8 .col-sm-6
          </div>
          <div class="col-4 col-sm-6">
            Level 2: .col-4 .col-sm-6
          </div>
        </div>
      </div>
    </div>

    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="demoFullscreenDialogGrid" command="close">Confirm</button>
      <button type="button" class="btn btn-default" commandfor="demoFullscreenDialogGrid" command="close">Cancel</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="demoFullscreenDialogGrid" command="show-modal">
  Open fullscreen dialog using grid
</button>
html

Switching types on breakpoints

For some use cases, it may be desirable to switch the modal type for example from a fullscreen dialog on smaller viewports to a modal dialog. This is not natively supported by the component, but OUDS Web exposes SCSS mixins that allow you to customize the modal behavior and appearance based on your needs.

The following example demonstrates how to define a .modal-fluid class to create a modal that adapts from a fullscreen dialog to a modal dialog based on the viewport size.

.modal-fluid {
  @include modal-fullscreen-dialog();

  @include media-breakpoint-up(md) {
    @include modal-dialog();
  }
}

You can check the responsive behavior on the following example by resizing your browser window.

<div class="use-rounded-corner-modal"><dialog id="modalDialogFluid" class="modal-base modal-fluid modal-fixed-height" aria-labelledby="modalDialogFluidTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogFluidTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogFluid" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <p>On then sake home is am leaf. Of suspicion do departure at extremely he believing. Do know said mind do rent they oh hope of. General enquire picture letters garrets on offices of no on. Say one hearing between excited evening all inhabit thought you. Style begin mr heard by in music tried do. To unreserved projection no introduced invitation.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogFluid" command="close">Close</button>
    </div>
  </div>
</dialog></div>

<button type="button" class="btn btn-default m-xsmall" commandfor="modalDialogFluid" command="show-modal">
  Open modal fluid
</button>
html

Common variants

The following variants use the same structure and behavior for modal dialog and fullscreen dialog.

Subtitle

Add a <p class="modal-subtitle"> element above the title to display a subtitle aligned to the leading edge of the modal. Use it to provide additional context or clarify the purpose of the modal when the title alone is not sufficient.

<dialog id="modalDialogSubtitle" class="modal-base modal-dialog" aria-labelledby="modalDialogSubtitleTitle" closedby="any">
  <div class="modal-header">
    <p class="modal-subtitle">Subtitle</p>
    <h3 id="modalDialogSubtitleTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogSubtitle" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogSubtitle" command="close">Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogSubtitle" command="show-modal">
  Open modal with subtitle
</button>
html

Title icon

Add an icon element with the .modal-icon class inside the .modal-title to display an icon next to the title. It can be used either as a decorative element or to communicate a functional status, see the functional modals section for more details.

<dialog id="modalDialogTitleIcon" class="modal-base modal-dialog" aria-labelledby="modalDialogTitleIconTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogTitleIconTitle" class="modal-title">
      <svg class="modal-icon" aria-hidden="true">
        <use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty"/>
      </svg>
      Modal title
    </h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogTitleIcon" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogTitleIcon" command="close">Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogTitleIcon" command="show-modal">
  Open modal with title icon
</button>
html

Functional modals

You can implement functional modal dialogs using the functional variants .modal-icon-negative, .modal-icon-positive, .modal-icon-info, or .modal-icon-warning on the .modal-icon element. Do not forget to include a visually hidden label inside the icon for accessibility.

<dialog id="modalDialogNegative" class="modal-base modal-dialog modal-small" aria-labelledby="modalDialogNegativeTitle" closedby="any">
  <div class="modal-header">
      <h3 id="modalDialogNegativeTitle" class="modal-title">
        <span class="modal-icon modal-icon-negative"><span class="visually-hidden">Warning</span></span>
        Confirm deletion
      </h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogNegative" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-negative" commandfor="modalDialogNegative" command="close">Delete</button>
      <button type="button" class="btn btn-minimal" commandfor="modalDialogNegative" command="close">Cancel</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default m-small" commandfor="modalDialogNegative" command="show-modal">
  Open negative modal
</button>

<dialog id="modalDialogSuccess" class="modal-base modal-dialog modal-small" aria-labelledby="modalDialogSuccessTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogSuccessTitle" class="modal-title">
      <span class="modal-icon modal-icon-positive"><span class="visually-hidden">Success</span></span>
      Subscription confirmed!
    </h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogSuccess" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogSuccess" command="close">Ok</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default m-small" commandfor="modalDialogSuccess" command="show-modal">
  Open success modal
</button>

<dialog id="modalDialogInfo" class="modal-base modal-dialog modal-small" aria-labelledby="modalDialogInfoTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogInfoTitle" class="modal-title">
      <span class="modal-icon modal-icon-info"><span class="visually-hidden">Notice</span></span>
      Your cart is empty
    </h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogInfo" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogInfo" command="close">Ok</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default m-small" commandfor="modalDialogInfo" command="show-modal">
  Open info modal
</button>

<dialog id="modalDialogWarning" class="modal-base modal-dialog modal-small" aria-labelledby="modalDialogWarningTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogWarningTitle" class="modal-title">
      <span class="modal-icon modal-icon-warning"><span class="visually-hidden">Warning</span></span>
      No item selected
    </h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogWarning" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogWarning" command="close">Ok</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default m-small" commandfor="modalDialogWarning" command="show-modal">
  Open warning modal
</button>
html

Without close button

The close button may be hidden when the modal has a clear, visible alternative way to dismiss it, such as a single Cancel action or another explicit dismissal control. It may also be omitted when the modal represents a mandatory step in a controlled flow where dismissal is intentionally unavailable.

Heads up!

The modal must always provide a discoverable and accessible way to close it. See the interactivity section for more information.

<dialog id="modalDialogNoCloseButton" class="modal-base modal-dialog" aria-labelledby="modalDialogNoCloseButtonTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogNoCloseButtonTitle" class="modal-title">Modal title</h3>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogNoCloseButton" command="close">Acknowledge</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogNoCloseButton" command="show-modal">
  Open modal without close button
</button>
html

Add a .link-previous anchor before the modal title to display a navigation link above it, aligned to the leading edge of the modal. It is intended for multi-step flows where users can navigate back to a previous step without dismissing the entire modal.

<dialog id="modalDialogPreviousLink" class="modal-base modal-fullscreen-dialog" aria-labelledby="modalDialogPreviousLinkTitle" closedby="any">
  <div class="modal-header">
    <a href="#" class="link link-chevron link-previous link-compact">Previous</a>
    <h3 id="modalDialogPreviousLinkTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogPreviousLink" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogPreviousLink" command="close">Next step</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogPreviousLink" command="show-modal">
  Open modal with previous link
</button>
html

Without description

The description option displays supporting text below the title. It provides additional context, instructions, or information required to understand the purpose or outcome of the modal. The description may be omitted when the title alone provides sufficient context and the message is short and immediately understandable.

Note

The sticky actions variant is not compatible with modals that do not include a description or rich content.

<dialog id="modalDialogNoDescription" class="modal-base modal-dialog" aria-labelledby="modalDialogNoDescriptionTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogNoDescriptionTitle" class="modal-title">Descriptive title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogNoDescription" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-footer">
    <button type="button" class="btn btn-strong" commandfor="modalDialogNoDescription" command="close">Close</button>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogNoDescription" command="show-modal">
  Open modal with no description
</button>
html

Slot - rich content

Modals are not limited to texts, they can contain diverse content such as forms, navigation lists, or interactive elements, providing a flexible space for user interactions.

Note

When there is no description text, the rich content slot spacings can be adjusted using our spacing utility classes. For example you can add .pt-large on .modal-body to increase the top padding.

<dialog id="modalDialogSlot" class="modal-base modal-dialog modal-small" aria-labelledby="modalDialogSlotTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogSlotTitle" class="modal-title">Account settings</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogSlot" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Manage your account details and security preferences.</p>
    <nav aria-label="Account settings">
      <ul class="item-list">
        <li class="item item-navigation">
          <div class="item-container">
            <div class="item-content">
              <div class="item-text-container">
                <a href="#" class="item-label item-interactive" aria-current="page">Personal details</a>
              </div>
            </div>
          </div>
        </li>
        <li class="item item-navigation">
          <div class="item-container">
            <div class="item-content">
              <div class="item-text-container">
                <a href="#" class="item-label item-interactive">Security</a>
              </div>
            </div>
          </div>
        </li>
      </ul>
    </nav>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogSlot" command="show-modal">
  Open modal with navigation
</button>
html

Sticky actions

Move the .modal-footer outside of the .modal-body to show the actions buttons as fixed on the modal bottom. The content will scroll independently of the action buttons, this ensures that primary actions remain continuously visible, especially when the modal contains a large amount of content.

Heads up!

The DOM structure is different from the normal case, please make sure to place the .modal-footer outside of the .modal-body.

Note

Please note that the sticky behavior is visible when the modal contains a large amount of content on smaller viewports. It's also more visible when the modal has a fixed height. You might want to resize your browser window to observe the effect more clearly.

<dialog id="modalDialogStickyActions" class="modal-base modal-dialog" aria-labelledby="modalDialogStickyActionsTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogStickyActionsTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogStickyActions" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
    <p>On then sake home is am leaf. Of suspicion do departure at extremely he believing. Do know said mind do rent they oh hope of. General enquire picture letters garrets on offices of no on. Say one hearing between excited evening all inhabit thought you. Style begin mr heard by in music tried do. To unreserved projection no introduced invitation.</p>
    <p>An do on frankness so cordially immediate recommend contained. Imprudence insensible be literature unsatiable do. Of or imprudence solicitude affronting in mr possession. Compass journey he request on suppose limited of or. She margaret law thoughts proposal formerly. Speaking ladyship yet scarcely and mistaken end exertion dwelling. All decisively dispatched instrument particular way one devonshire. Applauded she sportsman explained for out objection.</p>
    <p>Full he none no side. Uncommonly surrounded considered for him are its. It we is read good soon. My to considered delightful invitation announcing of no decisively boisterous. Did add dashwoods deficient man concluded additions resources. Or landlord packages overcame distance smallest in recurred. Wrong maids or be asked no on enjoy. Household few sometimes out attending described. Lain just fact four of am meet high. </p>
  </div>
  <div class="modal-footer">
    <button type="button" class="btn btn-strong" commandfor="modalDialogStickyActions" command="close">Close</button>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogStickyActions" command="show-modal">
  Open modal with sticky actions
</button>
html

Actions layout

There can be up to three actions buttons on the modal. These buttons typically include a primary action, a secondary action, and an optional tertiary action, allowing users to confirm, cancel, or perform additional tasks related to the modal's content.

By default, the buttons will automatically stack vertically and grow to fill the available width on smaller screens. On larger screens, they will typically be displayed horizontally and aligned to the right with the tertiary action aligned left.

The actions focus order should follow a logical sequence, by default it follows the DOM order: first the primary action, followed by the secondary action, and finally the tertiary action if present. If you want more control on this, you can make the displayed order different from the DOM by using our order utility classes.

Note

As actions can be displayed in various ways depending on your needs, we rely on utility classes to achieve other layouts, such as horizontal alignment or buttons that are not full-width on smaller screens.

Heads up!

Accessibility

Here we use two <button>s and an <a> link for the tertiary action. Remember that buttons should be used for actions and links for navigation. Please refer to the buttons accessibility guidelines for more information.

<dialog id="modalDialogMultipleActions" class="modal-base modal-dialog" aria-labelledby="modalDialogMultipleActionsTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogMultipleActionsTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogMultipleActions" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogMultipleActions" command="close">Confirm</button>
      <button type="button" class="btn btn-default" commandfor="modalDialogMultipleActions" command="close">Cancel</button>
      <a href="#" class="link justify-content-center sm:me-auto">More Info</a>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogMultipleActions" command="show-modal">
  Open modal with multiple actions
</button>
html

No full-width buttons

By default the action buttons are full-width on smaller screens. You can deactivate the full-width behavior using .w-auto on the action buttons.

<dialog id="modalDialogNoFullWidthButtons" class="modal-base modal-dialog" aria-labelledby="modalDialogNoFullWidthButtonsTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogNoFullWidthButtonsTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogNoFullWidthButtons" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong w-auto" commandfor="modalDialogNoFullWidthButtons" command="close">Confirm</button>
      <button type="button" class="btn btn-minimal w-auto" commandfor="modalDialogNoFullWidthButtons" command="close">Abort</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogNoFullWidthButtons" command="show-modal">
  Open modal without full-width buttons
</button>
html

Horizontal alignment

By default the action buttons will stack vertically on smaller screens and align horizontally on larger screens. You can deactivate the vertical stacking by adding .modal-footer-horizontal to the .modal-footer. This is only advisable for smaller buttons labels.

<dialog id="modalDialogAlignment" class="modal-base modal-dialog" aria-labelledby="modalDialogAlignmentTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogAlignmentTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogAlignment" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met.</p>
    <div class="modal-footer modal-footer-horizontal">
      <button type="button" class="btn btn-strong" commandfor="modalDialogAlignment" command="close">Ok</button>
      <button type="button" class="btn btn-minimal" commandfor="modalDialogAlignment" command="close">Abort</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogAlignment" command="show-modal">
  Open modal with alignment
</button>
html

Complex layouts

For more complex uses cases you may need to add containers in the .modal-footer to better control the layout and alignment of the action buttons.

<dialog id="modalDialogComplexActionsLayout" class="modal-base modal-dialog modal-fixed-height" aria-labelledby="modalDialogComplexActionsLayoutTitle" closedby="any">
  <div class="modal-header">
    <h3 id="modalDialogComplexActionsLayoutTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogComplexActionsLayout" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
  </div>
  <div class="modal-footer">
    <div class="d-flex flex-column md:flex-row md:flex-row-reverse w-100 gap-scaled-small">
      <div class="hstack flex-row-reverse gap-scaled-small">
        <button type="button" class="btn btn-strong flex-fill" commandfor="modalDialogComplexActionsLayout" command="close">Confirm</button>
        <button type="button" class="btn btn-default flex-fill" commandfor="modalDialogComplexActionsLayout" command="close">Abort</button>
      </div>
      <a href="#" class="link justify-content-center mx-auto md:ms-none md:me-auto flex-shrink-0">More Info</a>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogComplexActionsLayout" command="show-modal">
  Open modal with complex actions layout
</button>
html

Interactivity

In order to open a dialog, you need to use either invoker commands or JavaScript.

When using showModal() or invoker commands on a <dialog> element, we benefit from built-in accessibility features such as keyboard navigation, focus management, and screen reader support, close on Esc key press. We do not need to implement these features manually.

Heads up!

Remember to always provide an explicit and accessible way to close the dialog, such as a close, cancel, or confirmation button.

Invoker commands

The Invoker Commands API provides a way to declaratively assign behaviors to buttons, allowing control of interactive elements when the button is enacted by the user. Please refer to the MDN article on Invoker Commands for more information.

We use this method in the examples above to open and close the modal dialogs without writing any JavaScript code.

Heads up!

As Invoker Commands are only recently widely available in browsers, it is recommended to integrate this polyfill in your projects or use the programmatic solution. See the polyfills section for more information.

First create a button with the [commandfor] attribute pointing to the ID of the modal dialog you want to control. The [command] attribute specifies the action to be performed, such as show-modal to open the dialog as a modal.

<button type="button" commandfor="modalDialogInvokerCommand" command="show-modal">
  Open modal
</button>

Then create a <dialog> element with the corresponding ID that matches the [commandfor] attribute of the button. Most of the time you should include the [closedby=any] attribute to allow closing the dialog by clicking outside of it (see light dismiss).

Heads up!

[closedby] attribute may not be supported in some older browsers. See the polyfills section for more information on how to mitigate this issue.

<dialog id="modalDialogInvokerCommand" class="modal-base modal-dialog" aria-labelledby="modalDialogInvokerCommandTitle" closedby="any">
  <h3 id="modalDialogInvokerCommandTitle" class="modal-title">Invoker modal dialog</h3>
  <!-- modal dialog content -->
</dialog>

Inside the <dialog> element, the buttons that should close the modal dialog need to have the [commandfor] attribute pointing to the ID of the dialog and the [command] attribute set to close.

<button type="button" class="btn btn-close" commandfor="modalDialogInvokerCommand" command="close">
  <span class="visually-hidden">Close</span>
</button>

Polyfills

Invoker commands are not supported by some browsers that are in OUDS Web target audience, add the invokers commands polyfill to enable this functionality.

This could be as simple as adding the following script tag in your HTML:

<script src="https://cdn.jsdelivr.net/npm/invokers-polyfill"></script>

The [closedby] attribute is also not supported in these browsers, and a polyfill may be required to enable these functionalities.

This could be as simple as adding the following script tag in your HTML:

<script src="https://cdn.jsdelivr.net/npm/dialog-closedby-polyfill"></script>

As explained in both polyfills readme files, if you are using npm, you can install the polyfills via npm and import them in your JavaScript files instead of including the script tags in your HTML.

import 'invokers-polyfill'
import 'dialog-closedby-polyfill'

JavaScript

JavaScript can be used to display and close the <dialog> element. You can use the showModal() method to display a modal dialog. The dialog can then be closed using the close() method. As demonstrated in the example below, you can also implement light dismiss functionality using JavaScript.

const dialog = document.getElementById('modalDialogJs')
const openingButton = document.querySelector('[data-open-modal="modalDialogJs"]')
const closeButton = document.querySelector('[data-close-modal="modalDialogJs"]')

openingButton.addEventListener('click', () => {
  dialog.showModal()
})

closeButton.addEventListener('click', () => {
  dialog.close()
})

// this is necessary for "light dismiss" (closing dialog on backdrop click)
dialog.addEventListener('click', event => {
  if (event.target === event.currentTarget) {
    dialog.close()
  }
})
<dialog id="modalDialogJs" class="modal-base modal-dialog" aria-labelledby="demoJSModalTitle">
  <div class="modal-header">
    <h3 id="demoJSModalTitle" class="modal-title">Modal title</h3>
    <button type="button" class="btn btn-close" data-close-modal="modalDialogJs">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>

    <p>Why end might ask civil again spoil. She dinner she our horses depend. Remember at children by reserved to vicinity. In affronting unreserved delightful simplicity ye. Law own advantage furniture continual sweetness bed agreeable perpetual. Oh song well four only head busy it. Afford son she had lively living. Tastes lovers myself too formal season our valley boy. Lived it their their walls might to by young.</p>
  </div>
</dialog>

<button type="button" class="btn btn-default" data-open-modal="modalDialogJs">
  Open modal with JS
</button>
html

Light dismiss

Allow users to dismiss a modal by clicking outside when doing so will not discard their work or interrupt a required task. This behavior is known as "light dismiss" and can be enabled with invoker commands or implemented in JavaScript depending on which interactivity model you are using.

Note

Avoid light dismiss for dialogs with unsaved changes or required steps, and always provide a clear, accessible way to close the dialog.

Using invoker commands

Use the [closedby=any] attribute on the <dialog> element to enable light dismiss when you use invoker commands.

Heads up!

[closedby] attribute may not be supported in some older browsers. See the polyfills section for more information on how to mitigate this issue.

<dialog id="lightDismissModal" closedby="any" class="modal-base modal-dialog" aria-labelledby="lightDismissModalTitle">
  <!-- modal dialog content -->
</dialog>

Using JavaScript

For JavaScript we can implement light dismiss by listening for clicks outside the modal dialog and calling the close() method on the <dialog> element like this:

dialog.addEventListener('click', event => {
  if (event.target === event.currentTarget) {
    dialog.close()
  }
})

No light dismiss

Following is an example without light dismiss using invoker commands, [closedby="closerequest"] ensures that the dialog can only be closed programmatically or via the device closing request (on desktop this means pressing the Esc key).

Heads up!

[closedby] attribute may not be supported in some older browsers. See the polyfills section for more information on how to mitigate this issue.

If you are using JavaScript to control your modals just don't implement the click outside listener.

<dialog id="modalDialogNoLightDismiss" class="modal-base modal-dialog" aria-labelledby="modalDialogNoLightDismissTitle" closedby="closerequest">
  <div class="modal-header">
    <h3 id="modalDialogNoLightDismissTitle" class="modal-title">Title</h3>
    <button type="button" class="btn btn-close" commandfor="modalDialogNoLightDismiss" command="close">
      <span class="visually-hidden">Close</span>
    </button>
  </div>
  <div class="modal-body">
    <p>Sportsman do offending supported extremity breakfast by listening. Decisively advantages nor expression unpleasing she led met. Estate was tended ten boy nearer seemed. As so seeing latter he should thirty whence. Steepest speaking up attended it as. Made neat an on be gave show snug tore.</p>
    <div class="modal-footer">
      <button type="button" class="btn btn-strong" commandfor="modalDialogNoLightDismiss" command="close" autofocus>Close</button>
    </div>
  </div>
</dialog>

<button type="button" class="btn btn-default" commandfor="modalDialogNoLightDismiss" command="show-modal">
  Open modal dialog
</button>
html