Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/GoogleChrome/dialog-polyfill

Polyfill for the HTML dialog element
https://github.com/GoogleChrome/dialog-polyfill

a11y dialog html polyfill

Last synced: 8 days ago
JSON representation

Polyfill for the HTML dialog element

Lists

README 

        
dialog-polyfill.js is a polyfill for `` and ``.

Check out [some demos](https://googlechrome.github.io/dialog-polyfill/)!



`` is an element for a popup box in a web page, including a modal option which will make the rest of the page inert during use.

This could be useful to block a user's interaction until they give you a response, or to confirm an action.

See the [HTML spec](https://html.spec.whatwg.org/multipage/forms.html#the-dialog-element).



## Usage



### Installation



You may optionally install via NPM -



    $ npm install dialog-polyfill



There are several ways that to include the dialog polyfill:



* include `dist/dialog-polyfill.js` script directly in your HTML, which exposes a global `dialogPolyfill` function.

* `import` (es modules)

* `require` (commonjs/node)



```javascript

// direct import (script module, deno)

import dialogPolyfill from './node_modules/dialog-polyfill/dist/dialog-polyfill.esm.js';



// *OR*



// modern es modules with rollup/webpack bundlers, and node via esm module

import dialogPolyfill from 'dialog-polyfill'



// *OR*



// traditional commonjs/node and browserify bundler

const dialogPolyfill = require('dialog-polyfill')

```



### Supports



This polyfill works on modern versions of all major browsers.

It also supports IE9 and above.

It can work when used inside Shadow DOM, but it's not recommended.



### Steps



1. Include the CSS in the `` of your document, and the JS anywhere before referencing `dialogPolyfill`.

2. Create your dialog elements within the document. See [limitations](#limitations) for more details.

3. Register the elements using `dialogPolyfill.registerDialog()`, passing it one node at a time. This polyfill won't replace native support.

4. Use your `` elements!



## Script Global Example



```html



  



  

    I'm a dialog!

    

      

    

  

  

  

    var dialog = document.querySelector('dialog');

    dialogPolyfill.registerDialog(dialog);

    // Now dialog always acts like a native <dialog>.

    dialog.showModal();

  



```



### ::backdrop



In native ``, the backdrop is a pseudo-element.

When using the polyfill, the backdrop will be an adjacent element:



```css

dialog::backdrop { /* native */

  background-color: green;

}

dialog + .backdrop { /* polyfill */

  background-color: green;

}

```



## Limitations



In the polyfill, modal dialogs have limitations-



- They should not be contained by parents that create a stacking context, see below

- The browser's chrome may not always be accessible via the tab key

- Changes to the CSS top/bottom values while open aren't retained



### Stacking Context



The major limitation of the polyfill is that dialogs should not have parents that create [a stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context).

The easiest way to solve this is to move your `` element to be a child of ``.



If this isn't possible you may still be able to use the dialog.

However, you may want to resolve it for two major reasons-



1. The polyfill can't guarantee that the dialog will be the top-most element of your page

2. The dialog may be positioned incorrectly as they are positioned as part of the page layout _where they are opened_ (defined by spec), and not at a fixed position in the user's browser.



To position a dialog in the center (regardless of user scroll position or stacking context), you can specify the following CSS-



```css

dialog {

  position: fixed;

  top: 50%;

  transform: translate(0, -50%);

}

```



This is also provided as a helper CSS class in the polyfill CSS, `.fixed`.

You can apply by using HTML like ``.



## Extensions



### Focus



The WAI-ARIA doc suggests returning focus to the previously focused element after a modal dialog is closed.

However, this is not part of the dialog spec itself.

See [this snippet](https://gist.github.com/samthor/babe9fad4a65625b301ba482dad284d1) to add this, even to the native `dialog`.