details-dialog-element

<details-dialog> element

A modal dialog opened with a <details> button.

DEPRECATION WARNING

This web component has been deprecated. There are a number of accessibility concerns with this approach and so we no longer recommend using this component.

Accessibility and Usability Concerns

• Semantically, using a details-summary pattern for a dialog solution can be confusing for screen reader users.
• If the user performs a "find in page" operation on a website using details-dialog elements, the content on those elements will appear when they shouldn't.
• Opening the dialog does not disable scrolling on the underlying page.

GitHub are moving towards using a dialog Primer View Component which enforces certain aspects of the design (such as always having a close button and a title).

Installation

Available on npm as @github/details-dialog-element.

$ npm install --save @github/details-dialog-element

Usage

Script

Import as ES modules:

import '@github/details-dialog-element'

Include with a script tag:

Markup

  Open dialog
  
    Modal content
    Close
  

Deferred loading

Dialog content can be loaded from a server by embedding an [``][fragment] element.

  Robots
  
    Loading…
  

The src attribute value is copied to the the first time the button is toggled open, which starts the server fetch.

If the preload attribute is present, hovering over the `` element will trigger the server fetch.

Events

details-dialog-close

details-dialog-close event is fired from `` when a request to close the dialog is made from

• pressing escape,
• submitting a form[method="dialog"]
• clicking on summary, form button[formmethod="dialog"], [data-close-dialog], or
• dialog.toggle(false)

This event bubbles, and can be canceled to keep the dialog open.

document.addEventListener('details-dialog-close', function(event) {
  if (!confirm('Are you sure?')) {
    event.preventDefault()
  }
})

Browser support

Browsers without native custom element support require a polyfill.

• Chrome
• Firefox
• Safari
• Microsoft Edge

License

Distributed under the MIT license. See LICENSE for details.