Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oddbird/popover-polyfill
Polyfills the HTML popover attribute and showPopover/hidePopover/togglePopover methods onto HTMLElement, as well as the popovertarget and popovertargetaction attributes on <button> elements.
https://github.com/oddbird/popover-polyfill
Last synced: 5 days ago
JSON representation
Polyfills the HTML popover attribute and showPopover/hidePopover/togglePopover methods onto HTMLElement, as well as the popovertarget and popovertargetaction attributes on <button> elements.
- Host: GitHub
- URL: https://github.com/oddbird/popover-polyfill
- Owner: oddbird
- License: bsd-3-clause
- Created: 2022-07-11T14:58:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-08T17:44:13.000Z (about 1 month ago)
- Last Synced: 2024-10-29T18:48:50.275Z (13 days ago)
- Language: TypeScript
- Homepage:
- Size: 1.23 MB
- Stars: 259
- Watchers: 8
- Forks: 14
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Popover Attribute Polyfill
[](https://github.com/oddbird/popover-polyfill/actions/workflows/test.yml) [](https://badge.fury.io/js/@oddbird%2Fpopover-polyfill) [](https://app.netlify.com/sites/popover-polyfill/deploys)
- [Demo](https://popover-polyfill.netlify.app/)
- [Explainer](https://open-ui.org/components/popover.research.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.
## 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](https://unpkg.com/browse/@oddbird/popover-polyfill/dist/) and add it
to the appropriate directory in your project. Then, include it where necessary
with a `` tag:
```html
<script src="/path/to/popover.min.js" type="module">
```
Or without [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules):
```html
```
Note that the JS will inject CSS styles into your document (or ShadowRoot).
### With npm
For more advanced configuration, you can install with
[npm](https://www.npmjs.com/):
```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 from
`node_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';
```
### 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](https://blog.wesleyac.com/posts/why-not-javascript-cdn) such as
performance and robustness.
```html
```
## Usage
After installation the polyfill will automatically add the correct methods and
attributes to the HTMLElement class.
## 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.
- 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` to inject CSS onto the page (and each
Shadow DOM). If it can't use that it'll generate a `` 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 `adoptedStyleSheets` on Shadow Roots, if
you are building a ShadowRoot by setting `.innerHTML`, you'll remove the
StyleSheet. Either polyfill `adoptedStyleSheets` or call
`injectStyles(myShadow)` to add the styles back in.
- 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)`.
- 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](https://github.com/oddbird/popover-polyfill/issues/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:
```css
@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;`)
- 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.
## Contributing
Visit our [contribution guidelines](https://github.com/oddbird/popover-polyfill/blob/main/CONTRIBUTING.md).
## 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](https://www.oddbird.net/polyfill/#open-source-sponsors).
[Sponsor OddBird's OSS Work](https://opencollective.com/oddbird-open-source)