dialog element demo

The HTML dialog element provides in-page dialog box functionality. A dialog exists in the DOM tree and can be styled using ordinary CSS.

Your browser doesn't seem to support dialog element yet. This demo is running in polyfill mode.

Simplest Example

This won't show anything visually. You need to use JavaScript APIs to show / hide it.

<dialog>This is da dialog!</dialog>
This is da dialog!

.show() and .close() API

By using .show() and .close() API on dialog DOM element, you can show and close the dialog.

<dialog>
  <p>This is da dialog!</p>
  <button id="close">Close</button>
</dialog>
<button id="show">Open Dialog!</button>
var dialog = document.querySelector('dialog');
document.querySelector('#show').onclick = function() {
  dialog.show();
};
document.querySelector('#close').onclick = function() {
  dialog.close();
};

This is da dialog!


Styling dialog

The dialog isn't as fancy as you'd expected?. Yes, you can add arbitrary style to it as you would do to other block elements.

dialog {
  border: 1px solid rgba(0, 0, 0, 0.3);
  border-radius: 6px;
  box-shadow: 0 3px 7px rgba(0, 0, 0, 0.3);
}

Styling dialog is as easy as styling div!


.showModal() API

If you don't want the user to interact with things other than the dialog, you can open it modal. Simply call .showModal() instead of .show(). Notice you cannot select text in the background or click / tab to select buttons while the dialog is open.

Upon closing a dialog, a close event will be fired. Also, users can close a modal dialog by typing the "Escape" key. This will fire a cancel event which you can cancel using event.preventDefault().

var show = document.querySelector('#show');
show.addEventListener('click', function() {
  dialog.showModal();
  console.log('dialog opened');
});
show.addEventListener('close', function() {
  console.log('dialog closed');
});
show.addEventListener('cancel', function() {
  console.log('dialog canceled');
});

This layer is guaranteed to be on top of any other elements regardless of their z-index value, including previously opened modal dialogs.

You can optionally close the modal dialog using the "escape" key!


Adding modal dialog background color

To dim the page to hint to the user that it's not accessible, you can use the pseudo-element ::backdrop.

dialog::backdrop {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: rgba(0, 0, 0, 0.8);
}

Dim background using ::backdrop. It highlights the dialog and fades everything else away!


Returning a value from dialog

You can pass an argument to dialog.close(). The dialog.returnValue property will return the given value.

<dialog>
  <p>This is da dialog!</p>
  <input type="text" id="return_value" value="" placeholder="Enter value">
  <button id="close">Enter</button>
</dialog>
<button id="show">Open Dialog!</button>
document.querySelector('#close').onclick = function() {
  var value = document.querySelector('#return_value').value;
  dialog.close(value);
};
document.querySelector('dialog').addEventListener('close', function() {
  alert(this.returnValue);
});

Dialog receives an argument to close(). It will be reflected in .returnValue


Integration with a form

You can use form[method="dialog"] to integrate a form with a <dialog>. Upon form submission, it closes the dialog and sets dialog.returnValue to the value of the submit button that was used.

Also, you can use the autofocus attribute to automatically give focus to a form control inside the dialog when it pops up.

<dialog id="dialog">
  <form method="dialog">
    <p>Do you agree with terms of use?</p>
    <textarea class="form-control" disabled>Lorem ipsum dolor sit amet,....</textarea>
    <button type="submit" value="yes">Yes</button>
    <button type="submit" value="no" autofocus>No</button>
  </form>
</dialog>
<script>
 var dialog = document.getElementById('dialog');
 dialog.showModal();
 dialog.addEventListener('close', function (event) {
   if (dialog.returnValue == 'yes') {
     // ...
   } else {
     // ...
   }
 });
</script>

Do you agree with terms of use?



FAQ

Why do we need <dialog> element while it's possible using libraries?

Dialogs are such common UI components that it makes sense for the web platform to support them natively. This way you won't need a library just to popup a dialog.

<dialog> is also great for accessibility. The browser understands what element is a dialog and whether it's modal, so accessibility technology like screen readers can know which content should be non-interactive.

Also, modal dialogs are pushed on a well-ordered stack called the "top layer", rendered above all other elements, regardless of their z-index. Relying on z-index to put your modal dialog on top can be brittle in a complex web page. For example, the dialog may be stuck inside a low level stacking context, or other components may also try to be on top, or dynamic style changes may occur.

show and close are not linguistic opposites. Why not show/hide or open/close?

The HTML specification mandates the names show/close. The naming has been discussed extensively on the WHATWG mailing list and bug tracker, and show/close was upheld. Some important points are:

  • The <details> element has an boolean open property which indicates whether the element is open. If the methods for <dialog> were open/close, then dialog.open wouldn't be consistent with details.open.
  • HTML elements have a boolean property hidden. It would be inconsistent for <dialog> to use hide() which is unrelated to this hidden concept. The name should indicate something stronger than hiding.
  • show/close is consistent with the existing HTML API for native dialogs: showModalDialog()/close(). In fact, a study of various platform APIs revealed that show/close is a rather common naming.

One way to think about it may be: showing a dialog makes it open, and then you must close it to change that state. There is a set of concepts in the platform that relate to dialogs and elements: open, showing, closing, hidden, hiding, unhiding, and the naming choice should try to express them clearly.

The bulk of the discussion is part of this WHATWG mailing list thread. Feel free to weigh in if you feel you have input that hasn’t yet been represented.

How do I position a dialog?

Dialogs have some special positioning characteristics. When you call dialog.show(), the dialog is positioned in the center of the viewport by default. You can of course override this using ordinary CSS positioning such as setting top.

One thing to be aware of is that an absolutely positioned dialog's containing block is the initial containing block. So an absolutely positioned dialog is not affected by its ancestors for things like position, overflows, and percent lengths.

The spec includes anchored positioning, which lets you anchor a dialog to another element. However, it is not implemented in Chrome at this time.

* updated on 23th July 2014

Like many elements, <dialog> comes with default CSS which can be overriden. The default CSS includes "position: absolute; left: 0; right: 0; margin: auto;" which horizontally centers the element within its container.

Beyond the default CSS, modal <dialog> has some special positioning characteristics. First, a modal <dialog> lives in the top layer, which means that it’s above any z-index value. Also, it’s not affected by its ancestors for layout behavior like position, overflows, and percent lengths.

When you call dialog.showModal(), the dialog is vertically positioned in the center of the viewport. If you set the position manually using CSS top or bottom, you can override this behavior.

Non-modal <dialog> has no special positioning beyond the default CSS mentioned earlier.

Can I open multiple dialogs?

Yes. If the dialogs are non-modal, they behave much like multiple <div> elements. For modal <dialog>, the browser maintains a pending dialog stack. The top of the stack is the active modal dialog, which blocks the rest of the document. Whenever a modal dialog is opened, it is pushed to the top of the stack. Whenever a modal dialog is closed, it is removed from the stack. The dialogs are rendered in order of the stack, so the active dialog is the topmost.

Which browsers support <dialog>?

Currently (as of July 2014), Chrome supports <dialog> element (except anchor positioning).


Other resources

A polyfill is available on github. Check out the documentation.

Official specification of Dialog element can be found here.