Polymer Logo Home Start Get started Try Polymer Install Polymer 2.x Build an element 1. Get set up 2. Add local DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties Build an app 1. Get set up 2. Create a new page 3. Add some elements 4. Deploy Polymer Feature overview About this release What's new in 2.0 Upgrade guide Hybrid elements Release notes Custom elements Custom element concepts Define an element Declare properties 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 Tools Tools overview Polymer CLI CLI commands Create an element project Create an application project Document your elements Test your elements Publish your elements Web services polymer.json specification Node support Resources Glossary API Reference API Reference Global settings App Toolbox What's in the box? Using the Toolbox App templates Responsive app layout Routing Localization App storage Service worker Deploy Build for production Serve your app The PRPL pattern Case study Shop News Blog Community
Contents

Polymer 2.x has been developed alongside and tested with a new suite of v1-spec compatible polyfills for custom elements and shadow DOM. You can test Polymer 2.x by using the latest 1.0 version of webcomponentsjs, which is included as a bower dependency to Polymer 2.x. (webcomponentsjs versions prior to 1.0 support the older, v0 specifications for custom elements and shadow DOM.)

There are two main ways to load the polyfills:

  • webcomponents-lite.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.

  • 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.
  • apply-shim.html. A polyfill for CSS mixins. Unlike the other polyfills, it should be included 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="/bower_components/webcomponentsjs/webcomponents-loader.js"></script>

The webcomponents-lite.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: 
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 April 2017, there has been broad cross-browser agreement around the v1 versions of the Custom Elements and Shadow DOM APIs, with support in Chrome, Opera, and Safari Tech Preview, 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).

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

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

  • Firefox currently supports some of the v0 web component APIs behind a flag. Polymer does not work correctly with this flag enabled, because of an incompatibility with the web components polyfills.