/polyfills

Web Components Polyfills

Primary LanguageHTMLBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Web Components Polyfills

Test Status

Getting Started | Usage | Packages | Roadmap

The Web Components polyfills are a suite of JavaScript libraries that implement Web Components APIs for browsers that don't have built-in support.

If you use Custom Elements, Shadow DOM, or the <template> element, either directly or through a library like LitElement, then you can use these polyfills to make your app work in older browsers like IE11.

We're also working on polyfills for cutting edge new APIs for Web Components that aren't built into all modern browsers yet, like Shadow Parts and Adopted Stylesheets.

Getting Started

Install the webcomponentsjs package to get all of the Web Components polyfills and a loader that automatically downloads only the polyfills each browser needs:

npm install --save @webcomponents/webcomponentsjs

Load the polyfills loader before any of your application code:

<html>
  <head>
    <!-- If your application is compiled to ES5, then load this script first. -->
    <script src="./node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>

    <!-- Add support for Web Components to older browsers. -->
    <script src="./node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

    <!-- Load your application code anytime after loader.js -->
  </head>
  <body>
    <!-- Your custom elements will work in older browsers like IE11. -->
    <my-custom-element></my-custom-element>
  </body>
</html>

For more ways to load the Web Components polyfills, see the webcomponentsjs package.

Usage

The Web Components polyfills handle many usage patterns automatically, but there are certain patterns that require direct interaction with the library:

Setting Custom Properties

  • To set a CSS custom property value imperatively, pass the value to styleSubtree.

  • To re-compute CSS custom properties after a DOM mutuation that affects the matching condition of a CSS rule containing a custom property (e.g. changing a class attribute), call styleSubtree.

Registering styles

  • To use a style in the main document that sets or consumes a CSS Custom Property, register it with addCustomStyle.

  • To use a style in a Custom Element, pass the element's template to prepareTemplate before first cloning it. (Note that LitElement and the Polymer Library perform this registration step automatically.)

Packages

This repo is a monorepo. Each package lives under packages/<package>.

Published on npm webcomponentsjs

Documentation | Changelog | Issues

Loader and pre-minimized bundles for the full suite of Web Components polyfills.

Most users only need to install this package, but it is also possible to separately install any of the individual polyfills listed below.

Published on npm custom-elements

Documentation | Changelog | Issues

Polyfill for Custom Elements (MDN, Spec)

Published on npm template

Documentation | Changelog | Issues

Polyfill for Template Element (MDN, Spec)

Published on npm shadydom

Documentation | Changelog | Issues

Polyfill for Shadow DOM (MDN, Spec)

Published on npm shadycss

Documentation | Changelog | Issues

Polyfill for Scoped CSS (Spec)

Published on npm html-imports

Documentation | Changelog | Issues

Polyfill for HTML Imports (Spec)

Note that HTML Imports are deprecated in favor of JavaScript modules. As of Chrome 81, HTML Imports are no longer natively supported by any browser. The current version of the Web Components loader does not automatically polyfill HTML Imports. Applications that still depend on HTML Imports are recommended to install @webcomponents/html-imports and load it separately.

Roadmap

The following APIs are on the roadmap for 2020: