<modal-element>
A custom element to create a modal, using the native <dialog> element under the hood.
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
- Default configuration
- Native closing behavior
- Prevent closing
- Headerless modal
- No default close button
- Fullscreen modal
- Modal placement
- Scrollable content
- Preserve body overflow
- Custom styling
- Title truncation
- Custom backdrop
- Custom transitions
- No animations
- Invoker commands
- Stacked modals
- 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.
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
License
Licensed under the The MIT License (MIT)