<modal-element>

A custom element to create a modal, using the native <dialog> element under the hood.

Source code & documentation

Examples

Explore different configurations and use cases of the <modal-element> component through the examples below.

Open your browser's developer console to inspect the events dispatched by the component.

Table of contents
  1. Default configuration
  2. Native closing behavior
  3. Prevent closing
  4. Headerless modal
  5. No default close button
  6. Fullscreen modal
  7. Modal placement
  8. Scrollable content
  9. Preserve body overflow
  10. Custom styling
  11. Title truncation
  12. Custom backdrop
  13. Custom transitions
  14. No animations
  15. Invoker commands
  16. Stacked modals
  17. Interactive demo

Default configuration

This example demonstrates the modal's default configuration. You can close it using the default close button, clicking on the backdrop, or pressing the Esc key.

Example modal

This is a modal with the default configuration.

Source code
<button type="button" id="open-modal-button">Open modal</button>

<modal-element>
  <h2 slot="title">Example modal</h2>
  <p>This is a modal with the default configuration.</p>
</modal-element>

<script>
  const openButton = document.getElementById('open-modal-button');
  const modal = document.querySelector('modal-element');

  openButton.addEventListener('click', () => {
    modal.show();
  });
</script>

Native closing behavior

The closed-by attribute controls which user interactions can dismiss the modal. Setting it to closerequest prevents closing the modal by clicking on the backdrop, while still allowing the Esc key or the default close button to dismiss it.

Backdrop closing disabled

This modal uses closed-by="closerequest".

Clicking on the backdrop will not close the modal.

Close the modal by clicking the "X" button or pressing the Esc key.

Source code
<modal-element closed-by="closerequest">
  <h2 slot="title">Backdrop closing disabled</h2>
  <p>This modal uses <code>closed-by="closerequest"</code>.</p>
  <p>Clicking on the backdrop will not close the modal.</p>
</modal-element>

Prevent closing

You can prevent the modal from closing by listening to the modal-request-close event and calling event.preventDefault() in the event handler.

Custom close behavior

This modal will not close when clicking the "X" button, but it will close when clicking on the backdrop, pressing the Esc key, or clicking the Close button in the footer.

Source code
<modal-element id="modal-prevent-close">
  <h2 slot="title">Custom close behavior</h2>
  <p>
    This modal will not close when clicking the "X" button,
    but it will close when clicking on the backdrop,
    pressing the <kbd>Esc</kbd> key,
    or clicking the Close button in the footer.
  </p>
  <button slot="footer" type="button" commandfor="modal-prevent-close" command="--modal-close">
    Close
  </button>
</modal-element>

<script>
  const modal = document.querySelector('modal-element');

  modal.addEventListener('modal-request-close', evt => {
    if (evt.detail.reason === 'close-button') {
      evt.preventDefault();
    }
  });
</script>

Headerless modal

By adding the no-header attribute, the modal's header and default close button are hidden. You can still provide a title through the title slot to give the dialog an accessible name. Make sure to provide an alternative way to close the modal.

Headerless modal

This modal has no visible header but still has an accessible name.

Source code
<modal-element id="modal-no-header" no-header>
  <h2 slot="title">Headerless modal</h2>
  <p>This modal has no visible header but still has an accessible name.</p>
  <button slot="footer" type="button" commandfor="modal-no-header" command="--modal-close">
    Close
  </button>
</modal-element>

No default close button

By adding the no-close-button attribute, the modal will not have a default close button.

Alternative close button

This is a modal without default close button.

Source code
<modal-element id="modal-no-close-button" no-close-button>
  <h2 slot="title">Alternative close button</h2>
  <p>This is a modal without default close button.</p>
  <button slot="footer" type="button" commandfor="modal-no-close-button" command="--modal-close">
    Close
  </button>
</modal-element>

Fullscreen modal

By adding the fullscreen attribute, the modal will be displayed in fullscreen mode.

Fullscreen modal

This is a fullscreen modal.

Note, that --modal-width and --modal-height CSS Custom Properties are overriden when the modal is in fullscreen mode.

Source code
<modal-element fullscreen>
  <h2 slot="title">Fullscreen modal</h2>
  <p>This is a fullscreen modal.</p>
</modal-element>

Modal placement

By default, the modal is centered on the screen both vertically and horizontally. You can change the placement of the modal by using the placement attribute.

Placement

Change the placement of the modal by selecting one of the options below.

Modal placement

This is a modal with custom placement.

placement="center"

Source code
<modal-element placement="top-start">
  <h2 slot="title">Modal placement</h2>
  <p>This is a modal with custom placement.</p>
</modal-element>

<form name="modal-placement-form">
  <fieldset>
    <legend>Placement</legend>

    <label><input type="radio" name="placement" value="top-start" checked> Top Start</label>
    <label><input type="radio" name="placement" value="top-center"> Top Center</label>
    <label><input type="radio" name="placement" value="top-end"> Top End</label>

    <label><input type="radio" name="placement" value="center-start"> Center Start</label>
    <label><input type="radio" name="placement" value="center"> Center</label>
    <label><input type="radio" name="placement" value="center-end"> Center End</label>

    <label><input type="radio" name="placement" value="bottom-start"> Bottom Start</label>
    <label><input type="radio" name="placement" value="bottom-center"> Bottom Center</label>
    <label><input type="radio" name="placement" value="bottom-end"> Bottom End</label>
  </fieldset>
</form>

<script>
  const modal = document.querySelector('modal-element');
  const form = document.forms['modal-placement-form'];

  form.addEventListener('change', evt => {
    modal.setAttribute('placement', evt.target.value);
  });
</script>

Scrollable content

By design, the modal's height will not exceed that of the viewport. If the content is longer than the viewport, the body will scroll while the header and footer will remain fixed and visible.

Scrollable content

This is a modal with really long content. The header and footer will remain fixed, while the body will scroll.

Scroll down and see for yourself! 👇

Source code
<style>
  .long-content {
    min-height: 150vh; /* Really long body */
    border: 2px dashed currentColor;
    padding: 1rem;
  }
</style>

<modal-element id="modal-long-content">
  <h2 slot="title">Scrollable content</h2>
  <div class="long-content">
    <p>
      This is a modal with really long content.
      The header and footer will remain fixed, while the body will scroll.
    </p>
    <p>Scroll down and see for yourself! 👇</p>
  </div>
  <button slot="footer" type="button" commandfor="modal-long-content" command="--modal-close">
    Close
  </button>
</modal-element>

Preserve body overflow

By default, the modal will set the overflow property of the document's body to hidden when the modal is open. This is to prevent the body from scrolling when the modal is open. If you want to preserve the body overflow, you can add the preserve-overflow attribute to the modal.

Background scrolling enabled

This is a modal that preserves the body overflow. Try scrolling the document while the modal is open.

Source code
<modal-element preserve-overflow>
  <h2 slot="title">Background scrolling enabled</h2>
  <p>
    This is a modal that preserves the body overflow.
    Try scrolling the document while the modal is open.
  </p>
</modal-element>

Custom styling

Customize the modal's appearance using CSS Custom Properties and CSS Parts. The following example demonstrates how to style the header, body, footer, and close button.

A customized modal

This modal demonstrates how the component's appearance can be customized without changing its default behavior.

Notice the different backgrounds for the header, body, and footer, the borders separating each section, and the custom close button. These styles are applied using CSS Custom Properties and CSS Parts.

Source code
<style>
  modal-element {
    --modal-width: 35rem;
    --modal-border-width: 1px;
    --modal-border-color: var(--border);
    --modal-border-radius: 0.375rem;
    --modal-box-shadow: 0 0 0.5rem rgba(0, 0, 0, 0.25);
    --modal-header-background-color: var(--background-alt);
    --modal-body-background-color: var(--background-body);
    --modal-footer-background-color: var(--background-alt);
    --modal-backdrop-background: rgba(0, 0, 0, 0.7);
  }

  modal-element::part(header) {
    border-bottom: 1px solid var(--border);
  }

  modal-element::part(footer) {
    border-top: 1px solid var(--border);
  }

  modal-element::part(close) {
    background-color: var(--button-base);
    border: 1px solid var(--border);
    border-radius: 0.25rem;
    color: var(--text-bright);
    transition: background-color 0.2s ease;
  }

  modal-element::part(close):hover {
    background-color: var(--button-hover);
  }
</style>

<modal-element id="modal-custom-styling">
  <h2 slot="title">A customized modal</h2>
  <p>
    This modal demonstrates how the component's appearance can be customized
    without changing its default behavior.
  </p>
  <p>
    Notice the different backgrounds for the header, body, and footer,
    the borders separating each section, and the custom close button.
    These styles are applied using CSS Custom Properties and CSS Parts.
  </p>
  <button slot="footer" type="button" commandfor="modal-custom-styling" command="--modal-close">
    Close
  </button>
</modal-element>

Title truncation

By default, the modal's title will not be truncated if it's too long. You can override this behavior by using some CSS.

Lorem ipsum dolor sit amet consectetur adipisicing elit. Beatae quis eveniet dicta saepe rem impedit odio quisquam ducimus eaque animi laborum quod, iusto autem, nobis cumque, voluptate repellat quo ab?

This is a modal with a really long title.

Source code
<style>
  modal-element::part(title) {
    /* https://dfmcphee.com/flex-items-and-min-width-0 */
    min-width: 0;
  }

  modal-element [slot="title"] {
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
  }
</style>

<modal-element>
  <h2 slot="title">
    Lorem ipsum dolor sit amet consectetur adipisicing elit.
    Beatae quis eveniet dicta saepe rem impedit odio quisquam
    ducimus eaque animi laborum quod, iusto autem, nobis cumque,
    voluptate repellat quo ab?
  </h2>
  <p>This is a modal with a really long title.</p>
</modal-element>

Custom backdrop

Customize the modal's backdrop using the --modal-backdrop-background CSS Custom Property. This example uses a gradient instead of a solid color.

Gradient backdrop

This modal uses a custom gradient backdrop.

Source code
<style>
  .custom-backdrop {
    --modal-backdrop-background: linear-gradient(
      135deg,
      rgb(79 70 229 / 95%) 0%,
      rgb(147 51 234 / 90%) 50%,
      rgb(236 72 153 / 85%) 100%
    );
  }
</style>

<modal-element class="custom-backdrop">
  <h2 slot="title">Gradient backdrop</h2>
  <p>This modal uses a custom gradient backdrop.</p>
</modal-element>

Custom transitions

Customize the modal's opening and closing transitions using CSS. The opening transition relies on the @starting-style CSS at-rule, which requires browser support. By default, the component respects the prefers-reduced-motion media query and disables animations when the user has enabled reduced motion in their system settings.

Custom transitions

This is a modal with custom transitions.

Source code
<style>
  @media (prefers-reduced-motion: no-preference) {
    modal-element:not([no-animations])::part(base) {
      transition:
        transform 0.35s,
        opacity 0.35s,
        display 0.35s allow-discrete,
        overlay 0.35s allow-discrete;
    }

    /* IS-OPEN STATE */
    modal-element[open]:not([no-animations])::part(base) {
      transform: translateY(0);
      opacity: 1;
    }

    /* EXIT STATE */
    modal-element:not([no-animations])::part(base) {
      transform: translateY(-2rem);
      opacity: 0;
    }

    /* BEFORE-OPEN STATE */
    @starting-style {
      modal-element[open]:not([no-animations])::part(base) {
        transform: translateY(-2rem);
        opacity: 0;
      }
    }
  }
</style>

<modal-element>
  <h2 slot="title">Custom transitions</h2>
  <p>This is a modal with custom transitions.</p>
</modal-element>

No animations

By adding the no-animations attribute, the modal will not use animations on open and close.

Animations disabled

This is a modal that does not use animations on open and close.

Source code
<modal-element no-animations>
  <h2 slot="title">Animations disabled</h2>
  <p>This is a modal that does not use animations on open and close.</p>
</modal-element>

Invoker commands

With invoker commands you can open and close the modal in a declarative way using command and commandfor attributes on a button element.

The following button opens the modal using the --modal-open command.

Invoker-controlled modal

This is a modal that can be controlled using invoker commands.

You can close the modal by clicking the button below. This button uses the --modal-close command.

Source code
<button type="button" commandfor="modal-invoker-commands" command="--modal-open">
  Open modal
</button>

<modal-element id="modal-invoker-commands">
  <h2 slot="title">Invoker-controlled modal</h2>
  <p>This is a modal that can be controlled using invoker commands.</p>
  <button slot="footer" type="button" commandfor="modal-invoker-commands" command="--modal-close">
    Close
  </button>
</modal-element>

Stacked modals

This example demonstrates how to open a second modal on top of an already open modal using Invoker Commands.

Each modal automatically preserves and restores the previous body overflow value. Closing the modals in reverse order ensures that background scrolling remains disabled until both are closed.

Although stacking modals is supported, it is generally discouraged from a user experience perspective and should be avoided when possible.

First modal

This is a modal from which you can open another modal.

Second modal

This is a modal that was opened on top of another modal.

Source code
<button type="button" commandfor="modal-stacked-first" command="--modal-open">
  Open modal
</button>

<modal-element id="modal-stacked-first">
  <h2 slot="title">First modal</h2>
  <p>This is a modal from which you can open another modal.</p>
  <button slot="footer" type="button" commandfor="modal-stacked-second" command="--modal-open">
    Open second modal
  </button>
</modal-element>

<modal-element id="modal-stacked-second">
  <h2 slot="title">Second modal</h2>
  <p>This is a modal that was opened on top of another modal.</p>
</modal-element>

Interactive demo

Explore the component's features using the interactive demo below. Change the options to see how they affect the modal's appearance and behavior.

Interactive demo

Attributes

Change the modal's attributes to see how they affect its appearance and behavior.

Native closing behavior (closed-by)

Prevent closing

Select which close requests should be prevented.

Custom styling

License

Licensed under the The MIT License (MIT)