• Stars
    star
    255
  • Rank 159,729 (Top 4 %)
  • Language
    TypeScript
  • License
    BSD 3-Clause "New...
  • Created over 2 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Polyfills the HTML popover attribute and showPopover/hidePopover/togglePopover methods onto HTMLElement, as well as the popovertarget and popovertargetaction attributes on <button> elements.

Popover Attribute Polyfill

Build Status npm version Netlify Status

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 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';

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.

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 <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 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 for more.

Contributing

Visit our contribution guidelines.

More Repositories

1

susy

Pre-grid responsive layout toolkit for Sass, now deprecated
SCSS
3,868
star
2

true

Sass unit tests
SCSS
683
star
3

css-anchor-positioning

Polyfill for CSS Anchor Positioning
TypeScript
248
star
4

sassdoc-theme-herman

An Odd SassDoc theme.
JavaScript
117
star
5

cascading-color-system

CSS Custom Property color-theming
SCSS
71
star
6

susysite

Source for the new susy.oddbird.net
CSS
59
star
7

css-toggles

CSS Toggles demo and polyfill
JavaScript
58
star
8

css-sandbox

A place to draft & experiment with CSS proposals
Nunjucks
53
star
9

accoutrement

Combined Sass Accoutrement tools, with option for individual module imports
SCSS
36
star
10

accoutrement-color

Color helpers
CSS
32
star
11

oddcontrast

Svelte
28
star
12

blend

More color options for sass…
SCSS
26
star
13

show-when

An element that shows or hides based on provided conditions
JavaScript
22
star
14

slide-deck

Web presentations, as a self-contained web component
JavaScript
20
star
15

odd-browser

A place to explore ideas towards a site-building & networking browser
17
star
16

oddsite

⛔️ DEPRECATED: Old (unused) OddBird site
HTML
17
star
17

sliiides

An 11ty attempt at web presentations
Nunjucks
17
star
18

sass-json-export

JSON exporter for Sass. Based on SassyJSON, by Kitty Giraudel.
SCSS
12
star
19

vuefinder

mia-style slideshows with nuxt
Vue
11
star
20

portfoliyo

A communication tool for teachers and parents
Python
11
star
21

accoutrement-scale

Size and scale helpers for typography and layout
CSS
9
star
22

accoutrement-init

browser normalization and baseline defaults
CSS
6
star
23

greenmud

into the green green mud
JavaScript
6
star
24

accoutrement-maps

Sass map helpers
CSS
5
star
25

oddleventy

Official OddBird Site
Nunjucks
5
star
26

source-element

An exploratory Web Component to conditionally load one of several scripts based on user and browser settings.
JavaScript
4
star
27

PyFly

Python
3
star
28

mlt

Python
3
star
29

polyfill-template

TypeScript
3
star
30

cascade-layers-polyfill-demo

HTML
3
star
31

portfoliyo-landing

A landing page for the Portfoliyo project
JavaScript
2
star
32

accoutrement-type

Font helpers
CSS
2
star
33

susy.oddbird.net

New home for the Susy website
CSS
2
star
34

mozdemos

Demos for Mozilla Developer Channel – https://youtube.com/MozillaDeveloper
HTML
2
star
35

knet

Collecting stories of inspiration for teachers
Python
2
star
36

start-testing-preso

A talk on testing for PyCon US 2013
JavaScript
2
star
37

buntpress

PHP
1
star
38

set-your-code-free-preso

A presentation by Carl Meyer for PyCon 2014
CSS
1
star
39

rectangles

Vue
1
star
40

mahjongg

Concise scoring summary for Classical European style mahjongg
Ruby
1
star
41

project-templates

JavaScript
1
star
42

accoutrement-layout

Layout helpers in Sass
CSS
1
star
43

herman-test-project

a test project for sassdoc-theme-herman
CSS
1
star
44

bugdash

A "release readiness" and work prioritization dashboard for Bugzilla users.
JavaScript
1
star
45

accoutrement-queries

Media-query helpers
CSS
1
star
46

oddtools

project management tools for oddbird
JavaScript
1
star
47

advanced-python-preso

A presentation by Carl Meyer for ConFoo 2014, on advanced Python techniques.
CSS
1
star
48

sass-colors-sample

Sample code for implementing support of CSS color spaces in Sass
SCSS
1
star
49

accoutrement-reset

Reset helpers
CSS
1
star
50

odddocker

A base Docker image for OddBird web projects
Dockerfile
1
star