{"id":13594916,"url":"https://github.com/oddbird/popover-polyfill","last_synced_at":"2025-05-14T11:12:44.569Z","repository":{"id":44562370,"uuid":"512801038","full_name":"oddbird/popover-polyfill","owner":"oddbird","description":"Polyfills the HTML popover attribute and showPopover/hidePopover/togglePopover methods onto HTMLElement, as well as the popovertarget and popovertargetaction attributes on \u003cbutton\u003e elements.","archived":false,"fork":false,"pushed_at":"2025-05-08T20:48:14.000Z","size":1362,"stargazers_count":298,"open_issues_count":9,"forks_count":14,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-08T21:43:34.538Z","etag":null,"topics":["css","polyfill"],"latest_commit_sha":null,"homepage":"https://popover.oddbird.net","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oddbird.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"oddbird","open_collective":"oddbird-open-source"}},"created_at":"2022-07-11T14:58:32.000Z","updated_at":"2025-05-07T10:53:12.000Z","dependencies_parsed_at":"2023-02-14T19:32:02.418Z","dependency_job_id":"83388fb0-7153-481a-afc0-5144509b8d52","html_url":"https://github.com/oddbird/popover-polyfill","commit_stats":{"total_commits":447,"total_committers":22,"mean_commits":"20.318181818181817","dds":0.7695749440715883,"last_synced_commit":"9ca1dd55450fd2c1f8bc480e466bb5125f2e9f63"},"previous_names":["oddbird/popup-polyfill"],"tags_count":34,"template":false,"template_full_name":"oddbird/polyfill-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fpopover-polyfill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fpopover-polyfill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fpopover-polyfill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddbird%2Fpopover-polyfill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oddbird","download_url":"https://codeload.github.com/oddbird/popover-polyfill/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254071263,"owners_count":22009762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","polyfill"],"created_at":"2024-08-01T16:01:40.877Z","updated_at":"2025-05-14T11:12:44.556Z","avatar_url":"https://github.com/oddbird.png","language":"TypeScript","funding_links":["https://github.com/sponsors/oddbird","https://opencollective.com/oddbird-open-source"],"categories":["TypeScript"],"sub_categories":[],"readme":"# Popover Attribute Polyfill\n\n[![Build Status](https://github.com/oddbird/popover-polyfill/actions/workflows/test.yml/badge.svg)](https://github.com/oddbird/popover-polyfill/actions/workflows/test.yml) [![npm version](https://badge.fury.io/js/@oddbird%2Fpopover-polyfill.svg)](https://badge.fury.io/js/@oddbird%2Fpopover-polyfill) [![Netlify Status](https://api.netlify.com/api/v1/badges/35bc7ba7-97a2-4e41-93ed-5141988adb1e/deploy-status)](https://app.netlify.com/sites/popover-polyfill/deploys)\n\n- [Demo](https://popover.oddbird.net/)\n- [Explainer](https://open-ui.org/components/popover.research.explainer/)\n\nThis polyfills the HTML `popover` attribute and\n`showPopover`/`hidePopover`/`togglePopover` methods onto HTMLElement, as well as\nthe `popovertarget` and `popovertargetaction` attributes on Button elements.\n\n## Polyfill Installation\n\n### Download a copy\n\nThe simplest, recommended way to install the polyfill is to copy it into your\nproject.\n\nDownload `popover.js` (or `popover.min.js`) [from\nunpkg.com](https://unpkg.com/browse/@oddbird/popover-polyfill/dist/) and add it\nto the appropriate directory in your project. Then, include it where necessary\nwith a `\u003cscript\u003e` tag:\n\n```html\n\u003cscript src=\"/path/to/popover.min.js\" type=\"module\"\u003e\u003c/script\u003e\n```\n\nOr without [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules):\n\n```html\n\u003cscript src=\"/path/to/popover.iife.min.js\"\u003e\u003c/script\u003e\n```\n\nNote that the JS will inject CSS styles into your document (or ShadowRoot).\n\n### With npm\n\nFor more advanced configuration, you can install with\n[npm](https://www.npmjs.com/):\n\n```sh\nnpm install @oddbird/popover-polyfill\n```\n\nAfter installing, you’ll need to use appropriate tooling to use\n`node_modules/@oddbird/popover-polyfill/dist/popover.js`.\n\nFor most tooling such as Vite, Webpack, and Parcel, that will look like this:\n\n```js\nimport '@oddbird/popover-polyfill';\n```\n\nIf you want to manually apply the polyfill, you can instead import the\n`isSupported` and `apply` functions directly from\n`node_modules/@oddbird/popover-polyfill/dist/popover-fn.js` file.\n\nWith most tooling:\n\n```js\nimport { apply, isSupported } from '@oddbird/popover-polyfill/fn';\n```\n\nOr in CommonJS environments:\n\n```js\nconst { apply, isSupported } = require('@oddbird/popover-polyfill/fn');\n```\n\nAn `isPolyfilled` function is also available, to detect if the Popover methods\nhave been polyfilled:\n\n```js\nimport { isPolyfilled } from '@oddbird/popover-polyfill/fn';\n```\n\n### Via CDN\n\nFor prototyping or testing, you can use the npm package via a Content Delivery\nNetwork. Avoid using JavaScript CDNs in production, for [many good\nreasons](https://blog.wesleyac.com/posts/why-not-javascript-cdn) such as\nperformance and robustness.\n\n```html\n\u003cscript\n  src=\"https://cdn.jsdelivr.net/npm/@oddbird/popover-polyfill@latest\"\n  crossorigin=\"anonymous\"\n  defer\n\u003e\u003c/script\u003e\n```\n\n## Usage\n\nAfter installation the polyfill will automatically add the correct methods and\nattributes to the HTMLElement class.\n\n## Caveats\n\nThis polyfill is not a perfect replacement for the native behavior; there are\nsome caveats which will need accommodations:\n\n- A native `popover` has a `:popover-open` pseudo selector when in the open\n  state. Pseudo selectors cannot be polyfilled within CSS, and so instead the\n  polyfill will add the `.\\:popover-open` CSS class to any open popover. In\n  other words a popover in the open state will have `class=\":popover-open\"`. In\n  CSS the `:` character must be escaped with a backslash.\n\n  - The `:popover-open` selector within JavaScript methods has been polyfilled,\n    so both `.querySelector(':popover-open')` _and_\n    `.querySelector('.\\:popover-open')` will work to select the same element.\n    `matches` and `closest` have also been patched, so\n    `.matches(':popover-open')` will work the same as\n    `.matches('.\\:popover-open')`.\n\n  - Using native `:popover-open` in CSS that does not support native `popover`\n    results in an invalid selector, and so the entire declaration is thrown\n    away. This is important because if you intend to style a popover using\n    `.\\:popover-open` it will need to be a separate declaration. For example,\n    `[popover]:popover-open, [popover].\\:popover-open` will not work.\n\n- Native `popover` elements use the `:top-layer` pseudo element which gets\n  placed above all other elements on the page, regardless of overflow or\n  z-index. This is not possible to polyfill, and so this library simply sets a\n  really high `z-index`. This means if a popover is within an element that has\n  `overflow:` or `position:` CSS, then there will be visual differences between\n  the polyfill and the native behavior.\n\n- Native _invokers_ (that is, buttons or inputs using the `popovertarget`\n  attribute) on `popover=auto` will render in the accessibility tree as elements\n  with `expanded`. The only way to do this in the polyfill is setting the\n  `aria-expanded` attribute on those elements. This _may_ impact mutation\n  observers or frameworks which do DOM diffing, or it may interfere with other\n  code which sets `aria-expanded` on elements.\n\n- The polyfill uses `adoptedStyleSheets` and `new CSSStyleSheet()` to inject CSS\n  onto the page (and each Shadow DOM). If it can't use that it'll generate a\n  `\u003cstyle\u003e` tag instead. This means you may see a `\u003cstyle\u003e` tag you didn't put\n  there, and this _may_ impact mutation observers or frameworks.\n\n  - For browsers which don't support `new CSSStyleSheet()`, if you are building\n    a ShadowRoot by setting `.innerHTML`, you'll remove the StyleSheet. Call\n    `injectStyles(myShadow)` to add the styles back in:\n\n    ```js\n    let supportsCSSStyleSheet = false;\n    try {\n      new CSSStyleSheet();\n      supportsCSSStyleSheet = true;\n    } catch {}\n    const myShadow = myHost.attachShadow({ mode: 'open' });\n    myShadow.innerHTML = `...`;\n    if (!supportsCSSStyleSheet) {\n      injectStyles(myShadow);\n    }\n    ```\n\n  - Similarly, if you're using Declarative ShadowDOM or otherwise creating a\n    shadow root without calling `attachShadow`/`attachInternals`, then the\n    polyfill won't inject the styles (because it can't reference the\n    `shadowRoot`). You'll need to manually inject the styles yourself with\n    `injectStyles(myShadow)`.\n\n  - As a stylesheet is injected into the main document, if your host element is\n    a popover, styling with `:host` gets tricky beause `:host` styles always\n    take lower precedence than the main document styles. This is a limitation\n    of CSS and there's not a reasonable workaround. The best workaround for\n    now is to add `!important` to conflicting properties in your `:host` rule.\n    See [#147](https://github.com/oddbird/popover-polyfill/issues/147) for more.\n\n  - Given that the CSS is injected using JavaScript, you may find that you\n    temporarily see popovers as open while the JS is loading. To work around\n    this, you can add the following CSS to your project:\n\n    ```css\n    @supports not selector(:popover-open) {\n      [popover]:not(.\\:popover-open) {\n        display: none;\n      }\n    }\n    ```\n\n- When supported, the polyfill creates a cascade layer named `popover-polyfill`.\n  If your styles are not in layers then this should have no impact. If your\n  styles do use layers, you'll need to ensure the polyfill layer is declared\n  first. (e.g. `@layer popover-polyfill, other, layers;`)\n\n- While `togglePopover()` supports both the `force: boolean` and `{force:\nboolean, source: HTMLElement}` syntax, both `showPopover()` and\n  `togglePopover()` disregard the `source` parameter.\n\n- The polyfill will not work in browsers with partial popover support enabled,\n  and will also not attempt to make experimental support match the final spec.\n\n## Contributing\n\nVisit our [contribution guidelines](https://github.com/oddbird/popover-polyfill/blob/main/CONTRIBUTING.md).\n\n## Sponsor OddBird's OSS Work\n\nAt OddBird, we love contributing to the languages \u0026 tools developers rely on.\nWe're currently working on polyfills\nfor new Popover \u0026 Anchor Positioning functionality,\nas well as CSS specifications for functions, mixins, and responsive typography.\nHelp us keep this work sustainable\nand centered on your needs as a developer!\nWe display sponsor logos and avatars\non our [website](https://www.oddbird.net/polyfill/#open-source-sponsors).\n\n[Sponsor OddBird's OSS Work](https://opencollective.com/oddbird-open-source)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddbird%2Fpopover-polyfill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foddbird%2Fpopover-polyfill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddbird%2Fpopover-polyfill/lists"}