Notes:
A few things to note when using the <dialog> element.
window.#id.showModal()should be used to open the<dialog>.window.#id.open()can be used, however this comes with reduced accessibility and functionality. It's good to be aware of what each of these techniques to open the<dialog>does and to factor in any additional development for loss of functionality.- Using the
<dialog>element, means there is no 'click outside' (or the backdrop) to close the modal. However a user can still use the Esc key to close the<dialog>. - The
<dialog>element has an autofocus feature, which focuses the first selectable element when opening the modal. If content is scrollable and the first selectable element is at the bottom of the content it will focus and auto scroll to the bottom. This won't be desirable behaviour for this context, so have a plan to manage this. A good way to do it, is to autofocus a close button at the top so that when the modal opens, it does not automatically scroll to the bottom. - Close the
<dialog>element by submitting a form within the dialog (for pages that are not surrounded by a master form element), with<button formmethod="dialog">Cancel</button>. Useonclick="window.#id.close()"to close the element when not using a form inside the<dialog>. - Ensure that developers know what happens when a required input is used and how it affects closing the
<dialog>element. - Whilst the
<dialog>renders all other page elements inert, it does not stop page scrolling.
Dialog Element
Using the HTML <dialog> element for modals.
<button class="c-btn" onclick="window.dialog_box.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_box">
<button class="c-modal__overlay" type="button" onclick="window.dialog_box.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-content | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Title</h2>
<p>I'm a dialog.</p>
<div class="u-space-x-xs">
<button class="c-btn c-btn--primary" type="button">Confirm</button>
<button class="c-btn c-btn--tertiary" type="button" onclick="window.dialog_box.close();">Cancel</button>
</div>
</div>
</div>
</dialog>Box Sizes
A typical "boxed" modal, sizes can be adjusted with class modifiers.
<button class="c-btn" onclick="window.dialog_size_default.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_size_default">
<button class="c-modal__overlay" type="button" onclick="window.dialog_size_default.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-content | o-flow">
<h2 class="u-heading u-delta u-fw-500">Title</h2>
<p>I'm a default sized dialog box.</p>
<button class="c-btn" type="button" onclick="window.dialog_size_default.close();">Close</button>
</div>
</div>
</dialog><button class="c-btn" onclick="window.dialog_size_md.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box c-modal--box-md" id="dialog_size_md">
<button class="c-modal__overlay" type="button" onclick="window.dialog_size_md.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-content | o-flow">
<h2 class="u-heading u-delta u-fw-500">Title</h2>
<p>I'm a medium sized dialog box.</p>
<button class="c-btn" type="button" onclick="window.dialog_size_md.close();">Close</button>
</div>
</div>
</dialog><button class="c-btn" onclick="window.dialog_size_lg.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box c-modal--box-lg" id="dialog_size_lg">
<button class="c-modal__overlay" type="button" onclick="window.dialog_size_lg.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-content | o-flow">
<h2 class="u-heading u-delta u-fw-500">Title</h2>
<p>I'm a larger sized dialog box.</p>
<button class="c-btn" type="button" onclick="window.dialog_size_lg.close();">Close</button>
</div>
</div>
</dialog>Body Elements
Layout options for the box modal include a header and footer useful for occasions when content within the modal is scrollable.
<button class="c-btn" onclick="window.dialog_header.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_header">
<button class="c-modal__overlay" type="button" onclick="window.dialog_header.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-header | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Modal Header</h2>
</div>
<div class="c-modal__body-content | o-flow">
<p>He says he's found the main computer to power the tractor beam that's holding the ship here. He'll try to make the precise location appear on the monitor. The tractor beam is coupled to the main reactor in seven locations. A power loss at one of the terminals will allow the ship to leave. I don't think you boys can help. I must go alone. Whatever you say.</p>
<p>Now he begs you to help him in his struggle against the Empire. I regret that I am unable to present my father's request to you in person, but my ship has fallen under attack and I'm afraid my mission to bring you to Alderaan has failed.</p>
<div class="u-space-x-xs">
<button class="c-btn c-btn--primary">Confirm</button>
<button class="c-btn c-btn--tertiary" type="button" onclick="window.dialog_header.close();">Cancel</button>
</div>
</div>
</div>
</dialog><button class="c-btn" onclick="window.dialog_footer.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_footer">
<button class="c-modal__overlay" type="button" onclick="window.dialog_footer.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-content | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Modal Title</h2>
<p>He says he's found the main computer to power the tractor beam that's holding the ship here. He'll try to make the precise location appear on the monitor. The tractor beam is coupled to the main reactor in seven locations. A power loss at one of the terminals will allow the ship to leave. I don't think you boys can help. I must go alone. Whatever you say.</p>
<p>Now he begs you to help him in his struggle against the Empire. I regret that I am unable to present my father's request to you in person, but my ship has fallen under attack and I'm afraid my mission to bring you to Alderaan has failed.</p>
</div>
<div class="c-modal__body-footer | o-flow">
<span class="o-split">
<b class="o-split__title">Modal Footer</b>
<button class="c-btn" type="button" onclick="window.dialog_footer.close();">Close</button>
</span>
</div>
</div>
</dialog><button class="c-btn" onclick="window.dialog_all.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_all">
<button class="c-modal__overlay" type="button" onclick="window.dialog_all.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__close">
<button class="c-btn c-btn--clear c-modal__exit" type="button" onclick="window.dialog_all.close();">
<span class="u-hidden">Close Dialog</span>
<svg class="c-icon c-icon--lg" viewbox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path fill="none" stroke-linecap="round" stroke-width="2" d="m6 6 12 12M6 18 18 6"/>
</svg>
</button>
</div>
<div class="c-modal__body">
<div class="c-modal__body-header | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Modal Header</h2>
</div>
<div class="c-modal__body-content | o-flow">
<p>He says he's found the main computer to power the tractor beam that's holding the ship here. He'll try to make the precise location appear on the monitor. The tractor beam is coupled to the main reactor in seven locations. A power loss at one of the terminals will allow the ship to leave. I don't think you boys can help. I must go alone. Whatever you say.</p>
<p>Now he begs you to help him in his struggle against the Empire. I regret that I am unable to present my father's request to you in person, but my ship has fallen under attack and I'm afraid my mission to bring you to Alderaan has failed.</p>
</div>
<div class="c-modal__body-footer | o-flow">
<div class="o-split">
<b class="o-split__title">Modal Footer</b>
<div class="u-space-x-xs">
<button class="c-btn c-btn--primary" type="button">Confirm</button>
<button class="c-btn c-btn--tertiary" type="button" onclick="window.dialog_all.close();">Close</button>
</div>
</div>
</div>
</div>
</dialog>Managing Overflow
When space is limited i.e when on a mobile device, ensure the content is scroll-able within the modal.
<button class="c-btn" onclick="window.dialog_scroll.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_scroll">
<button class="c-modal__overlay" type="button" onclick="window.dialog_scroll.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-content | u-h-20 | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Title</h2>
<p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Consequuntur, ullam. Natus assumenda sint dicta! Quos eveniet voluptatem vel, consectetur hic ullam error accusantium, quod necessitatibus fugit ducimus quae nemo quisquam!</p>
<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Reiciendis quos harum excepturi iste, dolore adipisci aliquid soluta? Quisquam, quidem commodi? Molestias, ab. Iure, autem quae eligendi veniam saepe assumenda cupiditate?</p>
<div class="u-space-x-xs">
<button class="c-btn c-btn--primary" type="button">Confirm</button>
<button class="c-btn c-btn--tertiary" type="button" onclick="window.dialog_scroll.close();">Close</button>
</div>
</div>
</div>
</dialog><button class="c-btn" onclick="window.dialog_scroll_header.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_scroll_header">
<button class="c-modal__overlay" type="button" onclick="window.dialog_scroll_header.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-header | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Title</h2>
</div>
<div class="c-modal__body-content | u-h-20 | o-flow">
<p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Consequuntur, ullam. Natus assumenda sint dicta! Quos eveniet voluptatem vel, consectetur hic ullam error accusantium, quod necessitatibus fugit ducimus quae nemo quisquam!</p>
<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Reiciendis quos harum excepturi iste, dolore adipisci aliquid soluta? Quisquam, quidem commodi? Molestias, ab. Iure, autem quae eligendi veniam saepe assumenda cupiditate?</p>
<div class="u-space-x-xs">
<button class="c-btn c-btn--primary" type="button">Confirm</button>
<button class="c-btn c-btn--tertiary" type="button" onclick="window.dialog_scroll_header.close();">Close</button>
</div>
</div>
</div>
</dialog><button class="c-btn" onclick="window.dialog_scroll_footer.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_scroll_footer">
<button class="c-modal__overlay" type="button" onclick="window.dialog_scroll_footer.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-content | u-h-20 | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Title</h2>
<p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Consequuntur, ullam. Natus assumenda sint dicta! Quos eveniet voluptatem vel, consectetur hic ullam error accusantium, quod necessitatibus fugit ducimus quae nemo quisquam!</p>
<p>Lorem ipsum dolor sit amet consectetur adipisicing elit. Reiciendis quos harum excepturi iste, dolore adipisci aliquid soluta? Quisquam, quidem commodi? Molestias, ab. Iure, autem quae eligendi veniam saepe assumenda cupiditate?</p>
</div>
<div class="c-modal__body-footer | o-flow">
<div class="o-split">
<b class="o-split__title">Modal Footer</b>
<div class="u-space-x-xs">
<button class="c-btn c-btn--primary" type="button">Confirm</button>
<button class="c-btn c-btn--tertiary" type="button" onclick="window.dialog_scroll_footer.close();">Cancel</button>
</div>
</div>
</div>
</div>
</dialog><button class="c-btn" onclick="window.dialog_scroll_all.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_scroll_all">
<button class="c-modal__overlay" type="button" onclick="window.dialog_scroll_all.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__body">
<div class="c-modal__body-header | o-flow">
<h2 class="u-heading u-gamma u-fw-500">Title</h2>
</div>
<div class="c-modal__body-content | u-h-20 | o-flow">
<p>He says he's found the main computer to power the tractor beam that's holding the ship here. He'll try to make the precise location appear on the monitor. The tractor beam is coupled to the main reactor in seven locations. A power loss at one of the terminals will allow the ship to leave. I don't think you boys can help. I must go alone. Whatever you say.</p>
<p>Now he begs you to help him in his struggle against the Empire. I regret that I am unable to present my father's request to you in person, but my ship has fallen under attack and I'm afraid my mission to bring you to Alderaan has failed.</p>
</div>
<div class="c-modal__body-footer | o-flow">
<div class="o-split">
<b class="o-split__title">Modal Footer</b>
<div class="u-space-x-xs">
<button class="c-btn c-btn--primary" type="button">Confirm</button>
<button class="c-btn c-btn--tertiary" type="button" onclick="window.dialog_scroll_all.close();">Cancel</button>
</div>
</div>
</div>
</div>
</dialog>Close
Allow the dialog element to be closed with a "X" button.
<button class="c-btn" onclick="window.dialog_close.showModal();">Open Dialog</button>
<dialog class="c-modal c-modal--box" id="dialog_close">
<button class="c-modal__overlay" type="button" onclick="window.dialog_close.close()">
<span class="u-hidden">Close Modal</span>
</button>
<div class="c-modal__close">
<button class="c-btn c-btn--clear" type="button" onclick="window.dialog_close.close();">
<span class="u-hidden">Close Dialog</span>
<svg class="c-icon c-icon--lg" viewbox="0 0 24 24" width="16" height="16" aria-hidden="true">
<path fill="none" stroke-linecap="round" stroke-width="2" d="m6 6 12 12M6 18 18 6"/>
</svg>
</button>
</div>
<div class="c-modal__body">
<div class="c-modal__body-content | o-flow">
<h2 class="u-heading u-gamma u-fw-500">
Title
<svg class="c-icon | u-ml-xs" viewbox="0 0 16 16" width="16" height="16" aria-hidden="true">
<g fill="none" fill-rule="evenodd">
<path stroke-linecap="round" stroke-width="1.5" d="m6 10 7.5-7.5M7 2.5h6.5V9"/>
</g>
</svg>
</h2>
<p>He says he's found the main computer to power the tractor beam that's holding the ship here. He'll try to make the precise location appear on the monitor. The tractor beam is coupled to the main reactor in seven locations. A power loss at one of the terminals will allow the ship to leave. I don't think you boys can help. I must go alone. Whatever you say.</p>
<p>Now he begs you to help him in his struggle against the Empire. I regret that I am unable to present my father's request to you in person, but my ship has fallen under attack and I'm afraid my mission to bring you to Alderaan has failed.</p>
<button class="c-btn" type="button" onclick="window.dialog_close.close();">Close</button>
</div>
</div>
</dialog>Useful notes and reading:
Related Components:
Useful Links:
Support:
Support for the dialog element.
