Skip to content

Dialog

<quiet-dialog> stable since 1.0

Dialogs display modal content for alerts, confirmations, configurations, and other important interactions that require immediate attention.

Dialog

Curious cats explore every corner of their domain, gracefully leaping from windowsills to countertops, always seeking new adventures.

Close Show dialog 
<quiet-dialog id="dialog__overview">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Dialog
  </h3>

  <p>Curious cats explore every corner of their domain, gracefully leaping from windowsills to countertops, always seeking new adventures.</p>
  
  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__overview">Show dialog</quiet-button>

Examples Jump to heading

Opening and closing dialogs Jump to heading

You can open and close a dialog programmatically by obtaining a reference to it and setting the open property to true or false, respectively. 

const dialog = document.querySelector('quiet-dialog');

// Open the dialog
dialog.open = true;

// Close the dialog
dialog.open = false;

However, it's often more convenient for a button to control the dialog without additional scripting. In this case, you can add the data-dialog="open *" attribute to any button in the document, where * is the target dialog's id.

Similarly, you can add data-dialog="close" to any button inside a dialog to close it.

Opening and closing

The button you clicked has data-dialog="open id" so it opens the dialog that has a matching id.

The button below has data-dialog="close" so clicking it will close the dialog.

Close Show dialog 
<quiet-dialog id="dialog__opening">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Opening and closing
  </h3>

  <p>The button you clicked has <code>data-dialog="open <em>id</em>"</code> so it opens the dialog that has a matching id.</p>
  <p>The button below has <code>data-dialog="close"</code> so clicking it will close the dialog.</p>

  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__opening">Show dialog</quiet-button>

With header Jump to heading

Place elements into the header slot to add content at the start of the dialog.

With header

A playful kitten chases a red laser dot across the room, pouncing with determination while its tail twitches with excitement.

Show dialog 
<quiet-dialog id="dialog__header">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    With header
  </h3>

  <p>A playful kitten chases a red laser dot across the room, pouncing with determination while its tail twitches with excitement.</p>
</quiet-dialog>

<quiet-button data-dialog="open dialog__header">Show dialog</quiet-button>

Place elements into the footer slot to add actions or other supplemental information at the end of the dialog.

Gentle purrs fill the room as a content cat naps in a warm sunbeam, dreaming of chasing butterflies in the garden.

Close Show dialog 
<quiet-dialog id="dialog__footer">
  <p>Gentle purrs fill the room as a content cat naps in a warm sunbeam, dreaming of chasing butterflies in the garden.</p>

  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__footer">Show dialog</quiet-button>

Light dismissal Jump to heading

When clicking outside of a dialog, it will normally pulse briefly to draw the user's attention. If you want these clicks to dismiss the dialog instead, use the light-dismiss attribute.

Light dismissal

Clicking outside the dialog will cause it to close.

Close Show dialog 
<quiet-dialog light-dismiss id="dialog__light">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Light dismissal
  </h3>

  <p>Clicking outside the dialog will cause it to close.</p>

  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__light">Show dialog</quiet-button>

Customizing actions Jump to heading

By default, a close button is provided as a single action in the dialog's header. You can add your own header actions by slotting text buttons into the actions slot. Note that adding your own actions will remove the default close button.

Actions

Graceful cats leap through sunny windows. Their sleek whiskers twitch as they watch birds flutter past their perch.

Close Show dialog 
<quiet-dialog id="dialog__customizing">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Actions
  </h3>

  <quiet-button slot="actions" appearance="text" icon-label="Settings">
    <quiet-icon name="settings"></quiet-icon>
  </quiet-button>

  <quiet-button slot="actions" appearance="text" icon-label="Open in a new window">
    <quiet-icon name="external-link"></quiet-icon>
  </quiet-button>

  <quiet-button slot="actions" appearance="text" icon-label="Close" data-dialog="close">
    <quiet-icon name="x"></quiet-icon>
  </quiet-button>

  <p>Graceful cats leap through sunny windows. Their sleek whiskers twitch as they watch birds flutter past their perch.</p>
  
  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__customizing">Show dialog</quiet-button>

The actions slot is only available when the header is enabled.

Changing the placement Jump to heading

By default, dialogs appear in the center of the screen. To make the dialog slide in from the side of the screen like a drawer, set the placement attribute to start, end, top, or bottom.

Placement

Two mischievous cats prowl the kitchen countertops at midnight. Their glowing eyes search for forgotten treats and adventures.

Close
Start End Top Bottom 
<quiet-dialog id="dialog__placement">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Placement
  </h3>

  <p>Two mischievous cats prowl the kitchen countertops at midnight. Their glowing eyes search for forgotten treats and adventures.</p>

  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<div class="code-example-flex-wrap">
  <quiet-button data-placement="start">Start</quiet-button>
  <quiet-button data-placement="end">End</quiet-button>
  <quiet-button data-placement="top">Top</quiet-button>
  <quiet-button data-placement="bottom">Bottom</quiet-button>
</div>

<script>
  const dialog = document.getElementById('dialog__placement');
  const container = dialog.nextElementSibling;

  container.addEventListener('click', event => {
    dialog.placement = event.target.getAttribute('data-placement');
    dialog.open = true;
  });
</script>

The --width custom property has no effect on dialogs with top and bottom placements. Similarly, the --height custom property has no effect on dialogs with start and end placements.

Changing the size Jump to heading

The --width and --height custom properties control the default width and height of the dialog, respectively. On smaller screens, the dialog will shrink to fit the viewport.

Size

Lobortis feugiat vivamus at augue eget arcu dictum. Nulla at volutpat diam ut venenatis tellus in metus vulputate. Venenatis tellus in metus vulputate eu scelerisque felis.

Et malesuada fames ac turpis egestas maecenas pharetra. Eu lobortis elementum nibh tellus molestie nunc. Nisl purus in mollis nunc sed id semper risus in. Ultricies mi quis hendrerit dolor magna eget. Venenatis cras sed felis eget velit aliquet sagittis.

Close Show dialog 
<quiet-dialog id="dialog__width" style="--width: 800px;">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Size
  </h3>

  <p>Lobortis feugiat vivamus at augue eget arcu dictum. Nulla at volutpat diam ut venenatis tellus in metus vulputate. Venenatis tellus in metus vulputate eu scelerisque felis.</p>
  <p>Et malesuada fames ac turpis egestas maecenas pharetra. Eu lobortis elementum nibh tellus molestie nunc. Nisl purus in mollis nunc sed id semper risus in. Ultricies mi quis hendrerit dolor magna eget. Venenatis cras sed felis eget velit aliquet sagittis.</p>

  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__width">Show dialog</quiet-button>

Scrolling dialogs Jump to heading

Dialogs with overflowing content will expand as the viewport allows before scrolling. By design, the header and footer will remain visible so users don't get confused and have an easy way to exit the dialog.

The Chronicles of Cats

In the cozy corner of a sunlit room, a mysterious tabby cat named Shadow prowls with silent grace. Her whiskers twitch as she surveys her domain, a master of stealth and elegance. The morning light catches her fur, creating a mesmerizing dance of golden highlights across her perfectly groomed coat.

Nearby, a mischievous kitten named Pixel bounces from cushion to cushion, defying gravity with each leap. His tiny paws barely touch one surface before he's airborne again, a blur of energy and enthusiasm. The curtains flutter in his wake, marking his path of playful destruction.

In the kitchen windowsill, wise old Mr. Whiskers observes the garden with half-closed eyes. Birds flit past, catching his attention, but he merely twitches an ear – he's long past his bird-chasing days. Instead, he focuses on the important task of soaking up the warm sunshine, occasionally stretching out one paw in perfect contentment.

Luna, the elegant Siamese, practices her opera on the highest shelf of the bookcase. Her melodious complaints about dinner being four hours away echo through the house. She's convinced that her humans simply don't understand the concept of proper feeding schedules – clearly, anytime is dinner time.

Under the dining room table, partners in crime Socks and Mittens plot their next kitchen raid. Their synchronized tail swishes betray their excitement as they plan the optimal route to the treats stored in the highest cabinet. Their previous attempts may have failed, but cats are nothing if not persistent.

Out in the garden, adventurous explorer Captain Whiskers maps uncharted territory behind the rose bushes. Each rustle of leaves could hide a potential adversary – or worse, a cucumber. He approaches each step with military precision, his battle-scarred ear twitching at every sound.

Back inside, the newest family member, a tiny rescue named Pixel, discovers the joy of cardboard boxes. The expensive cat bed lies ignored as she claims a simple shipping box as her castle. Her purrs of contentment vibrate through the cardboard walls of her newfound kingdom.

Close Show dialog 
<quiet-dialog id="dialog__scrolling" reset-scroll>
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    The Chronicles of Cats
  </h3>

  <p>In the cozy corner of a sunlit room, a mysterious tabby cat named Shadow prowls with silent grace. Her whiskers twitch as she surveys her domain, a master of stealth and elegance. The morning light catches her fur, creating a mesmerizing dance of golden highlights across her perfectly groomed coat.</p>
  <p>Nearby, a mischievous kitten named Pixel bounces from cushion to cushion, defying gravity with each leap. His tiny paws barely touch one surface before he's airborne again, a blur of energy and enthusiasm. The curtains flutter in his wake, marking his path of playful destruction.</p>
  <p>In the kitchen windowsill, wise old Mr. Whiskers observes the garden with half-closed eyes. Birds flit past, catching his attention, but he merely twitches an ear – he's long past his bird-chasing days. Instead, he focuses on the important task of soaking up the warm sunshine, occasionally stretching out one paw in perfect contentment.</p>
  <p>Luna, the elegant Siamese, practices her opera on the highest shelf of the bookcase. Her melodious complaints about dinner being four hours away echo through the house. She's convinced that her humans simply don't understand the concept of proper feeding schedules – clearly, anytime is dinner time.</p>
  <p>Under the dining room table, partners in crime Socks and Mittens plot their next kitchen raid. Their synchronized tail swishes betray their excitement as they plan the optimal route to the treats stored in the highest cabinet. Their previous attempts may have failed, but cats are nothing if not persistent.</p>
  <p>Out in the garden, adventurous explorer Captain Whiskers maps uncharted territory behind the rose bushes. Each rustle of leaves could hide a potential adversary – or worse, a cucumber. He approaches each step with military precision, his battle-scarred ear twitching at every sound.</p>
  <p>Back inside, the newest family member, a tiny rescue named Pixel, discovers the joy of cardboard boxes. The expensive cat bed lies ignored as she claims a simple shipping box as her castle. Her purrs of contentment vibrate through the cardboard walls of her newfound kingdom.</p>
  
  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Close
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__scrolling">Show dialog</quiet-button>

By default, dialogs will maintain their scroll position when closed. Use the reset-scroll attribute to tell the dialog to reset scrolling each time it's closed.

Setting focus on open Jump to heading

To move focus to a specific form control when the dialog opens, add the autofocus attribute to it.

Autofocus

Close Show dialog 
<quiet-dialog id="dialog__focus">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Autofocus
  </h3>

  <quiet-text-field autofocus placeholder="Enter something"></quiet-text-field>

  <quiet-button slot="footer" data-dialog="close" variant="primary">Close</quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__focus">Show dialog</quiet-button>

Preventing the dialog from closing Jump to heading

You can stop the dialog from closing by preventing the quiet-before-close event. The dialog will briefly animate to draw the user's attention.

You can check event.detail.source to see which element triggered the dialog to close, such as a button. If the source is the dialog itself, you can assume that the user has pressed Escape or the dialog has been closed programmatically.

Try closing me

Only clicking the last button will close this dialog. Not even the Escape key will save you!

I won't close it Only I will close it Show dialog 
<quiet-dialog id="dialog__prevent">
  <h3 slot="header" style="font-size: 1.125rem; margin-block: 0;">
    Try closing me
  </h3>

  <p>Only clicking the last button will close this dialog. Not even the <kbd>Escape</kbd> key will save you!</p>

  <quiet-button slot="footer" data-dialog="close">
    I won't close it
  </quiet-button>
  
  <quiet-button slot="footer" data-dialog="close" variant="primary">
    Only I will close it
  </quiet-button>
</quiet-dialog>

<quiet-button data-dialog="open dialog__prevent">Show dialog</quiet-button>

<script>
  const dialog = document.getElementById('dialog__prevent');
  const closeButton = dialog.querySelector('quiet-button:last-of-type');

  dialog.addEventListener('quiet-before-close', event => {
    if (event.detail.source !== closeButton) {
      event.preventDefault();
    }
  });
</script>

For best results, avoid using this feature unless something severe will result from the user not making an explicit choice, e.g. data loss.

Styling dialogs Jump to heading

Dialogs come with a simple, minimal appearance. Feel free to customize them with your own styles. Here's a quick way to turn a dialog into an action sheet that works great on mobile devices.

Cancel Delete Delete 
<quiet-dialog class="dialog__action-sheet" placement="bottom" id="dialog__styling">
  <quiet-button data-dialog="close" pill>Cancel</quiet-button>
  <quiet-button variant="destructive" pill data-dialog="close">Delete</quiet-button>
</quiet-dialog>

<quiet-button variant="destructive" data-dialog="open dialog__styling">Delete</quiet-button>

<style>
  quiet-dialog.dialog__action-sheet::part(dialog) {
    background: transparent;
    box-shadow: none;
  }
  
  quiet-dialog.dialog__action-sheet::part(body) {
    display: flex;
    flex-direction: column;
    width: 100%;
    max-width: 500px;
    align-self: center;
    gap: 1rem;
}
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN npm

To manually import <quiet-dialog> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet-browser@1.0.0/dist/components/dialog/dialog.js';

To manually import <quiet-dialog> from npm, use the following code.

import '@quietui/quiet/dist/components/dialog/dialog.js';

Slots Jump to heading

Dialog supports the following slots. Learn more about using slots

Name Description
(default) Content to place in the dialog's body. Note that, due to this Chrome bug , you should wrap text nodes in an element to allow text selection in that browser.
header Content to place in the dialog's header.
actions Slot in one or more text buttons to customize the actions that appear in the dialog's header. Only available when the header is enabled.
footer Content to place in the dialog's footer.

Properties Jump to heading

Dialog has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute Description Reflects Type Default
open Opens or closes the dialog. boolean false
placement By default, the dialog will appear in the center of the screen. Changing the placement will cause the dialog to slide in from the side of the screen like a drawer. 'center'
'top'
'bottom'
'start'
'end' 		'center'
lightDismiss
light-dismiss 		Allows the dialog to be closed when clicking outside of it. boolean false
resetScroll
reset-scroll 		For dialogs that scroll, this will reset the scroll position when the dialog closes. boolean false

Methods Jump to heading

Dialog supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name Description Arguments
scrollBodyTo() Scrolls the dialog's body to the specified position. options: ScrollToOptions

Events Jump to heading

Dialog dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name Description
quiet-before-open Emitted when the dialog is instructed to open but before it is shown. Calling event.preventDefault() will prevent the dialog from opening.
quiet-open Emitted after the dialog has been opened and the show animation has completed.
quiet-before-close Emitted when the dialog is dismissed. Calling event.preventDefault() will prevent the dialog from closing and show a brief animation.

You can check event.detail.source to see which element triggered the dialog to close, such as a button. If the source is the dialog itself, the user has pressed Escape or the dialog has been closed programmatically.
quiet-close Emitted after the dialog has been closed and the hide animation has completed.

CSS custom properties Jump to heading

Dialog supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name Description Default
--height The default height of the dialog. Note that dialogs shrink to fit as necessary. fit-content
--show-duration The duration of the show/hide animation. 200ms
--spacing The spacing to use throughout the dialog. 1.5rem
--width The default width of the dialog. Note that dialogs shrink to fit as necessary. 30rem

CSS parts Jump to heading

Dialog exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name Description CSS selector
dialog The internal <dialog> element. ::part(dialog)
body The container that wraps the dialog's body. ::part(body)
header The container that wraps the dialog's header. A flex container, by default. ::part(header)
footer The container that wraps the dialog's footer. A flex container, by default. ::part(footer)

Custom States Jump to heading

Dialog has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name Description CSS selector
open Applied when the dialog is open. :state(open)
Search this website Toggle dark mode Get the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X

    No results found