Popover Attribute Polyfill

• Demo
• Explainer

This polyfills the HTML popover attribute and showPopover/hidePopover/togglePopover methods onto HTMLElement, as well as the popovertarget and popovertargetaction attributes on Button elements.

Browser Support

• Firefox 88+ (includes Android)
• Chrome 88+ (includes Android)
• Edge 88+
• Safari 14+ (includes iOS)

Polyfill Installation

Download a copy

The simplest, recommended way to install the polyfill is to copy it into your project.

Download popover.js (or popover.min.js) from unpkg.com and add it to the appropriate directory in your project. Then, include it where necessary with a <script> tag:

<script src="/path/to/popover.min.js" type="module"></script>

Or without JavaScript modules:

<script src="/path/to/popover.iife.min.js"></script>

Note that the JS will inject CSS styles into your document (or ShadowRoot).

With npm

For more advanced configuration, you can install with npm:

npm install @oddbird/popover-polyfill

After installing, you’ll need to use appropriate tooling to use node_modules/@oddbird/popover-polyfill/dist/popover.js.

For most tooling such as Vite, Webpack, and Parcel, that will look like this:

import '@oddbird/popover-polyfill';

If you want to manually apply the polyfill, you can instead import the isSupported and apply functions directly from node_modules/@oddbird/popover-polyfill/dist/popover-fn.js file.

With most tooling:

import { apply, isSupported } from '@oddbird/popover-polyfill/fn';

Or in CommonJS environments:

const { apply, isSupported } = require('@oddbird/popover-polyfill/fn');

An isPolyfilled function is also available, to detect if the Popover methods have been polyfilled:

import { isPolyfilled } from '@oddbird/popover-polyfill/fn';

Via CDN

For prototyping or testing, you can use the npm package via a Content Delivery Network. Avoid using JavaScript CDNs in production, for many good reasons such as performance and robustness.

<script
  src="https://cdn.jsdelivr.net/npm/@oddbird/popover-polyfill@latest"
  crossorigin="anonymous"
  defer
></script>

Usage

After installation the polyfill will automatically add the correct methods and attributes to the HTMLElement class.

Configuration

The polyfill supports an option to change the CSS layer name. When using the default version of the polyfill that executes automatically, options can be set by setting the value of window.POPOVER_POLYFILL_OPTIONS.

<script type="module">
  if (!("popover" in HTMLElement.prototype)) {
    window.POPOVER_POLYFILL_OPTIONS = {
      layerName: 'my-popover-polyfill-layer-name'
    };
    import("https://cdn.jsdelivr.net/npm/@oddbird/popover-polyfill@latest");
  }
</script>

When manually applying the polyfill, options can be set by passing an object as an argument.

<script type="module">
  if (!("popover" in HTMLElement.prototype)) {
    const { apply } = await import("https://cdn.jsdelivr.net/npm/@oddbird/popover-polyfill@latest");

    apply({
      layerName: 'my-popover-polyfill-layer-name',
    });
  }
</script>

Caveats

This polyfill is not a perfect replacement for the native behavior; there are some caveats which will need accommodations:

• A native popover has a :popover-open pseudo selector when in the open state. Pseudo selectors cannot be polyfilled within CSS, and so instead the polyfill will add the .\:popover-open CSS class to any open popover. In other words a popover in the open state will have class=":popover-open". In CSS the : character must be escaped with a backslash.

  • The :popover-open selector within JavaScript methods has been polyfilled, so both .querySelector(':popover-open') and .querySelector('.\:popover-open') will work to select the same element. matches and closest have also been patched, so .matches(':popover-open') will work the same as .matches('.\:popover-open').

  • Using native :popover-open in CSS that does not support native popover results in an invalid selector, and so the entire declaration is thrown away. This is important because if you intend to style a popover using .\:popover-open it will need to be a separate declaration. For example, [popover]:popover-open, [popover].\:popover-open will not work. If your browser support requirements allow you to use :where(), you can use [popover]:where(:popover-open, .\:popover-open) to target the native and polyfilled selectors.

• Native popover elements use the :top-layer pseudo element which gets placed above all other elements on the page, regardless of overflow or z-index. This is not possible to polyfill, and so this library simply sets a really high z-index. This means if a popover is within an element that has overflow: or position: CSS, then there will be visual differences between the polyfill and the native behavior.

• Native invokers (that is, buttons or inputs using the popovertarget attribute) on popover=auto will render in the accessibility tree as elements with expanded. The only way to do this in the polyfill is setting the aria-expanded attribute on those elements. This may impact mutation observers or frameworks which do DOM diffing, or it may interfere with other code which sets aria-expanded on elements.

• The polyfill uses adoptedStyleSheets and new CSSStyleSheet() to inject CSS onto the page (and each Shadow DOM). If it can't use that it'll generate a <style> tag instead. This means you may see a <style> tag you didn't put there, and this may impact mutation observers or frameworks.

  • For browsers which don't support new CSSStyleSheet(), if you are building a ShadowRoot by setting .innerHTML, you'll remove the StyleSheet. Call injectStyles(myShadow, layerName) (where layerName is optional) to add the styles back in:

    let supportsCSSStyleSheet = false;
    try {
      new CSSStyleSheet();
      supportsCSSStyleSheet = true;
    } catch {}
    const myShadow = myHost.attachShadow({ mode: 'open' });
    myShadow.innerHTML = `...`;
    if (!supportsCSSStyleSheet) {
      injectStyles(myShadow);
    }
    

  • Similarly, if you're using Declarative ShadowDOM or otherwise creating a shadow root without calling attachShadow/attachInternals, then the polyfill won't inject the styles (because it can't reference the shadowRoot). You'll need to manually inject the styles yourself with injectStyles(myShadow, layerName).

  • As a stylesheet is injected into the main document, if your host element is a popover, styling with :host gets tricky beause :host styles always take lower precedence than the main document styles. This is a limitation of CSS and there's not a reasonable workaround. The best workaround for now is to add !important to conflicting properties in your :host rule. See #147 for more.

  • Given that the CSS is injected using JavaScript, you may find that you temporarily see popovers as open while the JS is loading. To work around this, you can add the following CSS to your project:

    @supports not selector(:popover-open) {
      [popover]:not(.\:popover-open) {
        display: none;
      }
    }
    

• When supported, the polyfill creates a cascade layer named popover-polyfill. If your styles are not in layers then this should have no impact. If your styles do use layers, you'll need to ensure the polyfill layer is declared first. (e.g. @layer popover-polyfill, other, layers;). You can change the layer name by passing layerName to apply. (e.g. apply({ layerName: 'my-popover-polyfill-layer' })) or through window.POPOVER_POLYFILL_OPTIONS (see configuration)

• While togglePopover() supports both the force: boolean and {force: boolean, source: HTMLElement} syntax, both showPopover() and togglePopover() disregard the source parameter.

• The polyfill will not work in browsers with partial popover support enabled, and will also not attempt to make experimental support match the final spec.

• Native popover elements contain a ::backdrop pseudo-element when open. This behavior has not been added to the polyfill. To work around this, one option is to add a class to the body element when a popover is open:

  import { isPolyfilled } from '@oddbird/popover-polyfill/fn';
  
  const popovers = document.querySelectorAll('[popover]');
  const body = document.getElementById('body');
  
  if (isPolyfilled()) {
    for (const popover of popovers) {
      popover.addEventListener('toggle', () => {
        const popoverOpen = popover.matches(':popover-open');
        if (popoverOpen) {
          body.classList.add('open-popover');
        } else {
          body.classList.remove('open-popover');
        }
      });
    }
  }
  

  And then style the ::backdrop with CSS:

  ::backdrop,
  body.open-popover::before {
    content: '';
    background: /*backdrop styles*/;
    inset: 0;
    position: fixed;
    z-index: 1;
  }
  

  If your browser support requirements allow you to use :has(), the following CSS will work without the use of JavaScript:

  ::backdrop,
  body:has(.\:popover-open)::before {
    content: '';
    background: /*backdrop styles*/;
    inset: 0;
    position: fixed;
    z-index: 1;
  }
  

Contributing

Visit our contribution guidelines.

Sponsor OddBird's OSS Work

At OddBird, we love contributing to the languages & tools developers rely on. We're currently working on polyfills for new Popover & Anchor Positioning functionality, as well as CSS specifications for functions, mixins, and responsive typography. Help us keep this work sustainable and centered on your needs as a developer! We display sponsor logos and avatars on our website.

Sponsor OddBird's OSS Work