Popover Attribute Polyfill
npm install @oddbird/popover-polyfill  
This polyfills the HTML popover attribute andshowPopover/hidePopover/togglePopover methods onto HTMLElement, as well as
the popovertarget and popovertargetaction attributes on Button elements.
- Firefox 88+ (includes Android)
- Chrome 88+ (includes Android)
- Edge 88+
- Safari 14+ (includes iOS)
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
Or without JavaScript modules:
`html`
Note that the JS will inject CSS styles into your document (or ShadowRoot).
For more advanced configuration, you can install with
npm:
`sh`
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:
`js`
import '@oddbird/popover-polyfill';
If you want to manually apply the polyfill, you can instead import the
isSupported and apply functions directly fromnode_modules/@oddbird/popover-polyfill/dist/popover-fn.js file.
With most tooling:
`js`
import { apply, isSupported } from '@oddbird/popover-polyfill/fn';
Or in CommonJS environments:
`js`
const { apply, isSupported } = require('@oddbird/popover-polyfill/fn');
An isPolyfilled function is also available, to detect if the Popover methods
have been polyfilled:
`js`
import { isPolyfilled } from '@oddbird/popover-polyfill/fn';
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.
`html`
crossorigin="anonymous"
defer
>
After installation the polyfill will automatically add the correct methods and
attributes to the HTMLElement class.
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.\:popover-open
state. Pseudo selectors cannot be polyfilled within CSS, and so instead the
polyfill will add the CSS class to any open popover. Inclass=":popover-open"
other words a popover in the open state will have . In:
CSS the character must be escaped with a backslash.
- The :popover-open selector within JavaScript methods has been polyfilled,.querySelector(':popover-open')
so both _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
it will need to be a separate declaration. For example,[popover]:popover-open, [popover].\:popover-open
will not work.
- Native popover elements use the :top-layer pseudo element which getsz-index
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 . This means if a popover is within an element that hasoverflow:
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 will render in the accessibility tree as elementsexpanded
with . The only way to do this in the polyfill is setting thearia-expanded
attribute on those elements. This _may_ impact mutationaria-expanded
observers or frameworks which do DOM diffing, or it may interfere with other
code which sets 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