HTML <dialog> Tag

The HTML <dialog> tag indicates a part of an application that the user can interact with to perform a task. For example 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.

Syntax

The <dialog> tag is written as <dialog id=""></dialog> with the dialog content inserted between the start and end tags. The id attribute can be used to associate a script with the <dialog> element.

Like this:

<dialog id="">
	<p>Dialog content...</p>
	<button id="hide">Close</button>
</dialog>

Examples

Basic tag usage

Here's an example of the <dialog> element being used in its most basic form. The open attribute has been added, which means that the dialog is already open upon the page loading.

Opening/Closing the Dialog

In order for the user to be able to interact with the dialog box properly, you'll need to use a script (such as JavaScript). The HTMLDialogElement interface provides a number of methods and properties that allow you to control the dialog box (more about these below, under "The HTMLDialogElement Interface").

Styles

You can add styles to the <dialog> element by using CSS.

Modal Dialogs

You can create modal dialogs by using the showModal() method (as opposed to the show() method).

Modal dialogs create a mode where the main window can't be used until the user has interacted with the dialog (i.e. closed it). Most browsers tint the background color to a darker shade, which draws attention to the dialog box.

Note that you still need to use the close() method to close the dialog (i.e. there is no closeModal() method).

Styling Modal Dialogs

You can use the CSS ::backdrop pseudo class to change the color of the modal backdrop. That is, you can change the color or shading that the browser gives to the rest of the browser window when the modal dialog is open.

For example, dialog::backdrop {background-color: rgba(0, 255, 0, 0.5);} will make the backdrop green, with an opacity of 0.5. Like this:

The HTMLDialogElement Interface

As seen in the above examples, you can use JavaScript to control the <dialog> element. This is achieved via the HTMLDialogElement interface.

For more information on the HTMLDialogElement interface, see HTML5 <dialog> Tag.

Attributes

Attributes can be added to an HTML element to provide more information about how the element should appear or behave.

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

The <dialog> element accepts the following attributes.

Element-Specific Attributes

This table shows the attributes that are specific to the <dialog> 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.

Global Attributes

The following attributes are standard across all HTML5 elements. Therefore, you can use these attributes with the <dialog> tag (except for tabindex), as well as with all other HTML tags.

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

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

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.

Below are the standard HTML5 event handler content attributes.

Again, you can use any of these with the <dialog> element, as well as any other HTML5 element.

  • 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.

Differences Between HTML 4 & HTML 5

The <dialog> element was not part of HTML 4 and earlier specifications.

The <details> tag was also not implemented as part of the HTML5 specification. It has been implemented in the HTML 5.1 specification, as well as the WHATWG HTML Living Standard.

The <dialog> was originally added to the HTML5 specification with a completely different purpose (it was to represent a dialog between two people). It was subsequently dropped, then re-introduced (with a new purpose - its current purpose), then moved to the HTML 5.1 draft specification.

For more detail on the <dialog> element, see HTML5 <dialog> Tag. Also check out the links to the official specifications below.

Template

Here's a template for the <dialog> tag with all available attributes for the tag (based on HTML5). These are grouped into attribute types, each type separated by a space. In many cases, you will probably only need one or two (if any) attributes. Simply remove the attributes you don't need.

For more information on attributes for this tag, see HTML5 <dialog> Tag.

<dialog  
 open=""
 
 accesskey=""
 class=""
 contenteditable=""
 contextmenu=""
 dir=""
 draggable=""
 dropzone=""
 hidden=""
 id=""
 itemid=""
 itemprop=""
 itemref=""
 itemscope=""
 itemtype=""
 lang=""
 spellcheck=""
 style=""
 title=""
 translate=""

 onabort=""
 onautocomplete=""
 onautocompleteerror=""
 onblur=""
 oncancel=""
 oncanplay=""
 oncanplaythrough=""
 onchange=""
 onclick=""
 onclose=""
 oncontextmenu=""
 oncuechange=""
 ondblclick=""
 ondrag=""
 ondragend=""
 ondragenter=""
 ondragexit=""
 ondragleave=""
 ondragover=""
 ondragstart=""
 ondrop=""
 ondurationchange=""
 onemptied=""
 onended=""
 onerror=""
 onfocus=""
 oninput=""
 oninvalid=""
 onkeydown=""
 onkeypress=""
 onkeyup=""
 onload=""
 onloadeddata=""
 onloadedmetadata=""
 onloadstart=""
 onmousedown=""
 onmouseenter=""
 onmouseleave=""
 onmousemove=""
 onmouseout=""
 onmouseover=""
 onmouseup=""
 onmousewheel=""
 onpause=""
 onplay=""
 onplaying=""
 onprogress=""
 onratechange=""
 onreset=""
 onresize=""
 onscroll=""
 onseeked=""
 onseeking=""
 onselect=""
 onshow=""
 onsort=""
 onstalled=""
 onsubmit=""
 onsuspend=""
 ontimeupdate=""
 ontoggle=""
 onvolumechange=""
 onwaiting=""
	>
</dialog>

Tag Details

For more details about the <dialog> tag, see HTML5 <dialog> Tag.

Specifications

Here are the official specifications for the <dialog> element.

What's the Difference?

W3C creates "snapshot" specifications that don't change once defined. So the HTML5 specification won't change once it becomes an official recommendation. WHATWG on the other hand, develops a "living standard" that is updated on a regular basis. In general, you will probably find that the HTML living standard will be more closely aligned to the current W3C draft than to the HTML5 specification.