webcomponents.js (v1 spec polyfills)
Note. For polyfills that work with the older Custom Elements and Shadow DOM v0 specs, see the v0 branch.
Note. For polyfills that include HTML Imports, see the v1 branch.
A suite of polyfills supporting the Web Components specs:
- Custom Elements v1: allows authors to define their own custom tags (spec, tutorial, polyfill).
- Shadow DOM v1: provides encapsulation by hiding DOM subtrees under shadow roots (spec, tutorial, shadydom polyfill, shadycss polyfill).
For browsers that need it, there are also some minor polyfills included:
How to use
npm install @webcomponents/webcomponentsjs
You can also load the code from a CDN such as unpkg: https://unpkg.com/@webcomponents/webcomponentsjs@^2/
webcomponents-bundle.js contains all of the web components polyfills and is
suitable for use on any supported browser. All of the polyfill code will be loaded
but each polyfill will only be used based on feature detection.
The bundle includes Custom Elements, Shady DOM/CSS and generic platform polyfills
(such as ES6 Promise, Constructable events, etc.) (needed by Internet Explorer 11),
and Template (needed by IE 11 and Edge).
webcomponents-bundle.js is very simple to use but it does load code
that is not needed on most modern browsers, slowing page load. For best performance,
Here's an example:
<!-- load webcomponents bundle, which includes all the necessary polyfills --><!-- load the element --><!-- use the element -->
webcomponents-loader.js is a client-side loader that dynamically loads the
minimum polyfill bundle, using feature detection.
webcomponents-loader.js can be loaded synchronously, or asynchronously depending on your needs.
If you have inlined the source of
webcomponent-loader.js, then you should specify
window.WebComponents.root as the root from which to load the polyfills.
When loaded synchronously,
webcomponents-loader.js behaves similarly to
The appropriate bundle will be loaded with
document.write() to ensure that WebComponent polyfills are available for subsequent scripts and modules.
Here's an example:
<!-- load the webcomponents loader, which injects the necessary polyfill bundle --><!-- load the element --><!-- use the element -->
When loaded asychronously with the
defer attribute, polyfill bundles will be loaded asynchronously,
which means that scripts and modules that depend on webcomponents APIs must be loaded
WebComponents.waitFor function takes a callback function as an argument, and will evaluate that callback after the polyfill bundle has been loaded.
The callback function should load scripts that need the polyfills (typically via
should return a promise that resolves when all scripts have loaded.
Here's an example:
<!-- Load polyfills; note that "loader" will load these async --><!-- Load a custom element definitions in `waitFor` and return a promise --><!-- Use the custom element -->
WebComponents.waitFor function may be called multiple times, and the callback functions will be processed in order.
Here's a more complicated example:
<!-- Load polyfills; note that "loader" will load these async -->
WebComponentsReady event is fired when polyfills and user scripts have loaded and custom elements have been upgraded. This event is generally not needed; however, it may be useful in some cases like testing. If imperative code should wait until a specific custom element definition has loaded, it can use the platform
According to the spec, only ES6 classes (https://html.spec.whatwg.org/multipage/scripting.html#custom-element-conformance) may be passed to the native
customElements.define API. For best performance, ES6 should be served to browsers that support it, and ES5 code should be serve to those that don't. Since this may not always be possible, it may make sense to compile and serve ES5 to all browsers. However, if you do so, ES5-style custom element classes will now not work on browsers with native Custom Elements because ES5-style classes cannot properly extend ES6 classes, like
As a workaround, if your project has been compiled to ES5, load
custom-elements-es5-adapter.js before defining Custom Elements. This adapter will automatically wrap ES5.
The adapter must NOT be compiled.
The polyfills are intended to work in the latest versions of evergreen browsers. See below for our complete browser support matrix:
|Polyfill||Edge||IE11+||Chrome*||Firefox*||Safari 9+*||Chrome Android*||Mobile Safari*|
*Indicates the current version of the browser
The polyfills may work in older browsers, however require additional polyfills (such as classList, or other platform polyfills) to be used. We cannot guarantee support for browsers outside of our compatibility matrix.
- Style encapsulation (inline styling in components) does not work out of the box
- Custom element's constructor property is unreliable
- ShadyCSS: :host(.zot:not(.bar:nth-child(2))) doesn't work
The ShadowDOM polyfill does not properly support CSS in ShadowDoM out of the box:
- Any styles inside components have an effect on the whole document (instead of on the component only - the encapsulation is broken).
- Any shadow-dom specific selectors (like
:host) do not work.
You can fix those issues by manually calling the
ShadyCSS APIs. See ShadyCSS usage.
See #215 for background.
In Edge and IE, instances of Custom Elements have a
constructor property of
HTMLUnknownElement, respectively. It's unsafe to rely on this property for checking element types.
It's worth noting that
HTMLElementPrototype and that the prototype chain isn't modified by the polyfills(onto
:host() rules can only have (at most) 1-level of nested parentheses in its argument selector under ShadyCSS. For example,
:host(.zot:not(.bar)) both work, but
:host(.zot:not(.bar:nth-child(2))) does not.
If you wish to build the bundles yourself, you'll need
npm on your system:
- install node.js using the instructions on their website
npmto install gulp.js:
npm install -g gulp
- make sure you have Java installed per https://www.npmjs.com/package/google-closure-compiler#java-version
Now you are ready to build the polyfills with:
# install dependencies npm install # build npm run build
The builds will be placed into the root directory.
See the contributing guide
Everything in this repository is BSD style license unless otherwise specified.
Copyright (c) 2015 The Polymer Authors. All rights reserved.
Changes in version 2.x
- The HTML Imports polyfill has been removed. Given that ES modules have shipped in most browsers, the expectation is that web components code will be loaded via ES modules.
- When using
deferattribute, scripts that rely on the polyfills must be loaded using