HTML 5 <dialog> Tag

At the time of writing this element had limited browser support. If the above example looks weird, it's probably due to that.

The HTML <dialog> tag indicates a part of an application that the user can interact with. Examples of dialog could include a dialog box, inspector, or window.

The <dialog> element accepts a boolean attribute called open that sets the element to "active" and allows users to interact with it. If the attribute is omitted, you will need to use a script (such as JavaScript) to enable the dialog to open and close as required.

See here for more examples of usage.

The HTMLDialogElement Interface

As seen in the above example, you can use JavaScript to control the <dialog> element. This is achieved via the HTMLDialogElement interface (this interface is included in the HTML specifications for this element).

The HTMLDialogElement interface has a number of methods and properties that you can use to control your dialog boxes.

They are as follows.

Methods

show()
Shows the dialog box. The user can still interact with other elements in the HTML document while the dialog box is visible.
showModal()
Shows a "modal dialog". This type of dialog prevents the user from interacting with other elements on the page until they've closed the dialog. Browsers will often darken the rest of the page to draw attention to the dialog, and to provide the user with a visual clue that they need to acknowledge/close the dialog before they can continue.
close()
Closes the dialog. Accepts returnValue as an optional parameter. This parameter will update the returnValue property (below).

Properties

returnValue
Retrieves the optional parameter that was passed to the close() method (above).
open
This property contains a boolean value (either true or false). If true, the dialog is displayed to the user. Otherwise it is hidden.

Events

Whenever a <dialog> element is closed, the close event will be fired.

dialog.addEventListener('close', function() {
  ...code here...
});

Attributes

HTML tags can contain one or more attributes. Attributes are added to a tag to provide the browser with more information about how the tag should appear or behave. Attributes consist of a name and a value separated by an equals (=) sign, with the value surrounded by double quotes. Here's an example, style="color:black;".

There are 3 kinds of attributes that you can add to your HTML tags: Element-specific, global, and event handler content attributes.

The attributes that you can add to this tag are listed below.

Element-Specific Attributes

The following table shows the attributes that are specific to this tag/element.

AttributeDescription
openWhen this attribute is present, the <dialog> element is interactive and the user can interact with it. When the open attribute is not present, the <dialog> element is hidden from the user.

Note that the tabindex attribute (below) does not apply to <dialog> elements.

Global Attributes

The following attributes are standard across all HTML 5 tags.

  • accesskey
  • class
  • contenteditable
  • contextmenu
  • dir
  • draggable
  • dropzone
  • hidden
  • id
  • itemid
  • itemprop
  • itemref
  • itemscope
  • itemtype
  • lang
  • spellcheck
  • style
  • tabindex
  • title
  • translate

For a full explanation of these attributes, see HTML 5 global attributes.

Event Handler Content Attributes

Event handler content attributes enable you to invoke a script from within your HTML. The script is invoked when a certain "event" occurs. Each event handler content attribute deals with a different event.

Here are the standard HTML 5 event handler content attributes.

  • onabort
  • oncancel
  • onblur
  • oncanplay
  • oncanplaythrough
  • onchange
  • onclick
  • oncontextmenu
  • ondblclick
  • ondrag
  • ondragend
  • ondragenter
  • ondragexit
  • ondragleave
  • ondragover
  • ondragstart
  • ondrop
  • ondurationchange
  • onemptied
  • onended
  • onerror
  • onfocus
  • onformchange
  • onforminput
  • oninput
  • oninvalid
  • onkeydown
  • onkeypress
  • onkeyup
  • onload
  • onloadeddata
  • onloadedmetadata
  • onloadstart
  • onmousedown
  • onmousemove
  • onmouseout
  • onmouseover
  • onmouseup
  • onmousewheel
  • onpause
  • onplay
  • onplaying
  • onprogress
  • onratechange
  • onreadystatechange
  • onscroll
  • onseeked
  • onseeking
  • onselect
  • onshow
  • onstalled
  • onsubmit
  • onsuspend
  • ontimeupdate
  • onvolumechange
  • onwaiting

For a full explanation of these attributes, see HTML 5 event handler content attributes.

History of the <dialog> Element

When the <dialog> tag was first introduced into the HTML 5 draft specification, it had a different purpose. When it was first introduced, its purpose was to indicate a dialog between two or more people (for example, a conversation, meeting minutes, a chat transcript, a dialog in a screenplay, an instant message log). It was subsequently dropped from HTML 5, but then later re-introduced into the HTML 5.01 draft specification (as well as the HTML Living Standard) with a completely different purpose (of which is outlined in this current page).