Polymer Logo Home Guides Feature overview Try Polymer Install Polymer 3.x Tutorial: Build an element 1. Get set up 2. Add shadow DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties About this release What's new in 3.0 Upgrade guide Release notes Custom elements Custom element concepts Define an element Declare properties Working with legacy elements Shadow DOM & styling Shadow DOM concepts DOM templating Style shadow DOM Custom CSS properties Events Handle and fire events Gesture events Data system Data system concepts Work with object and array data Observers and computed properties Data binding Helper elements Browser support Overview Polyfills ES6 and modules Tools Tools overview Polymer CLI CLI commands Create an element project Create an application project Document your elements Test your elements polymer.json specification Node support Build apps Overview App templates Build for production Serve your app The PRPL pattern Service worker Reference Glossary Global settings API Reference index polymer-element.js Elements array-selector.js custom-style.js dom-bind.js dom-if.js dom-module.js dom-repeat.js Mixins dir-mixin.js disable-upgrade-mixin.js element-mixin.js gesture-event-listeners.js mutable-data.js properties-changed.js properties-mixin.js property-accessors.js property-effects.js strict-binding-parser.js template-stamp.js Utils array-splice.js async.js case-map.js debounce.js flattened-nodes-observer.js flush.js gestures.js html-tag.js mixin.js path.js render-status.js resolve-url.js settings.js style-gather.js telemetry.js templatize.js Legacy class.js legacy-data-mixin.js legacy-element-mixin.js mutable-data-behavior.js polymer-fn.js polymer.dom.js templatizer-behavior.js

The Polymer library is in maintenance mode. For new development, we recommend Lit.

Contents

Polymer 3.x has been developed alongside and tested with a new suite of v1-spec compatible polyfills for custom elements and shadow DOM. These versions no longer include the HTML imports polyfill, and have been developed to work with ES6 modules. You can test Polymer 3.x using the latest 2.0 version of webcomponentsjs v2.0.0 or later.

(Polyfill versions v1.x.x include the HTML imports polyfill, and are compatible with Polymer 2.x. Versions prior to v1.0 support the older, v0 specifications for custom elements and shadow DOM.)

There are two main ways to load the polyfills:

  • webcomponents-bundle.js includes all of the polyfills necessary to run on any of the supported browsers. Because all browsers receive all polyfills, this results in extra bytes being sent to browsers that support one or more feature. This replaces the v1.x webcomponents-lite.js bundle.

  • webcomponents-loader.js performs client-side feature-detection and loads just the required polyfills. This requires an extra round-trip to the server, but saves bandwidth for browsers that support one or more features.

In both cases, the polyfills should be loaded just once. The polyfills are generally loaded from the application entrypoint (index.html or similar).

There are a couple of other related polyfill files that you may need:

  • custom-elements-es5-adapter.js. This small polyfill allows you to run compiled, ES5 elements on browsers that support native custom elements. This is useful in static serving environments where you need to serve a single app version to all browsers. The adapter is discussed in more detail in ES6 and in Build for production. Important note: the es5 adapter must come before the webcomponents polyfills, if any.
  • apply-shim.js. A polyfill for CSS mixins. Unlike the other polyfills, it should be imported by any component that defines or applies CSS mixins. For details, see Use custom CSS mixins.

References:

By default, the individual polyfill for a given feature is disabled on browsers that natively support that feature. For testing purposes, you can force the polyfills on for browsers that have native support. You can force the polyfills on by adding a JavaScript snippet before you import the polyfills:

<script>
  // Force all polyfills on
  if (window.customElements) window.customElements.forcePolyfill = true;
  ShadyDOM = { force: true };
  ShadyCSS = { shimcssproperties: true};
</script>
<script src="./node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

The webcomponents-bundle.js file also supports forcing the polyfills on by adding query parameters to the app's URL:

https://www.example.com/my-application/view1?wc-ce&wc-shadydom&wc-shimcssproperties

The following table lists the JavaScript snippets and query parameters for each polyfill.

Polyfill Description
Custom Elements JavaScript: 
if (window.customElements) window.customElements.forcePolyfill = true;

Query parameter:

wc-ce

Shadow DOM JavaScript: 
ShadyDOM = { force: true }

Query parameter:

wc-shadydom

CSS custom properties JavaScript: 
ShadyCSS = { shimcssproperties: true}

Query parameter:

wc-shimcssproperties

As of May 2018 the v1 versions of the Custom Elements and Shadow DOM APIs have been shipped in Chrome, Opera, and Safari, and implementations underway in other browsers.

See caniuse.com for more information on native browser support for web components.

Notes:

  • Chrome natively implements both the v0 APIs (used by Polymer 1.x) and the v1 APIs (used by Polymer 2.x & 3.x).

  • Safari includes working implementations of Shadow DOM v1 and Custom Elements v1.

  • Firefox includes experimental implementations of Custom Elements v1 and Shadow DOM v1. These implementations are currently disabled by default but are expected to be enabled by about version 63.

  • Edge has on its backlog to support Shadow DOM v1 and Custom Elements v1.