Home Start Get started 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 Quick tour Define elements Register an element Declare properties Instance methods Behaviors Local DOM & styling Local DOM Styling 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 Tools Tools overview Polymer CLI Document your elements Test your elements Optimize for production Publish an element Advanced tools Services What's new Release notes 1.0 Migration guide About Polymer 1.0 Resources Community Browser compatibility API Reference Polymer.Base array-selector custom-style dom-bind dom-if dom-repeat dom-template Polymer.Templatizer Global settings App Toolbox What's in the box? Using the Toolbox App templates Responsive app layout Routing Localization App storage Service worker Serve your app Case study Shop News Blog Community Feature overview Quick tour
Define elements
Register an element Declare properties Instance methods Behaviors
Local DOM & styling
Local DOM Styling
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
Tools
Tools overview Polymer CLI Document your elements Test your elements Optimize for production Publish an element Advanced tools Services
What's new
Release notes 1.0 Migration guide About Polymer 1.0
Resources
Community Browser compatibility
API Reference
Polymer.Base array-selector custom-style dom-bind dom-if dom-repeat dom-template Polymer.Templatizer Global settings

Polymer 1.0+ works in the latest two versions of all major browsers: Safari 7+, IE 11+, and the evergreen Chrome, Firefox, and Edge.

Browser support

The Polymer library is a lightweight sugaring layer on top of the Web Components APIs. Unlike a typical javascript framework, Polymer is designed to leverage features baked into the web platform itself to let you build components. Some features used by Polymer are not (yet) supported natively in all browsers. For broad web components support, Polymer uses the polyfills from webcomponents.org. They're lightweight, work well, and provide the feature support Polymer requires.

With the polyfills, Polymer works in these browsers:

ChromeFirefoxIE 11+/EdgeSafari 7+Chrome (Android)Safari (iOS 7.1)
Template
HTML Imports
Custom Elements
Shadow DOM

Notes:

  • Older versions of the Android Browser may run into some issues - please file an issue if you run into a problem on this browser. Chrome for Android is supported.

  • We recommend conditionally loading the polyfills in your application: using the server or feature-detecting on the client whether the browser supports web components natively, and then only loading the polyfills if it doesn't. An advantage of using standards-based features is the payload necessary to run your application will continue to decrease as browsers implement the standard. If you've installed the polyfills using bower install --save webcomponents/webcomponentsjs, here is some example code for how to feature-detect on the client:

    (function() {
      if ('registerElement' in document
          && 'import' in document.createElement('link')
          && 'content' in document.createElement('template')) {
        // platform is good!
      } else {
        // polyfill the platform!
        var e = document.createElement('script');
        e.src = '/bower_components/webcomponentsjs/webcomponents-lite.min.js';
        document.body.appendChild(e);
      }
    })();
    

Should I use webcomponents-lite.js or webcomponents.js?

We recommend using the webcomponents-lite.js version of the polyfills with Polymer 1.0+. This version is designed to be used with Shady DOM, and does not contain the full Shadow DOM polyfill.

Although the full webcomponents.js polyfill works with Polymer 1.0+, we do not recommend using it. This version contains the full Shadow DOM polyfill, which is known to have high performance overhead.

See the webcomponents.js compatibility matrix for more details on support.

Other features used by Polymer or the elements

IE 10 has flaky Mutation Observer support, and is also largely no longer supported by Microsoft. Much of Polymer will still work, but you may run into some bugs here and there. "Official" support is for IE 11/Edge.

Progress of native browser support

As of 2016-05, there has been broad cross-browser agreement around the v1 versions of the Custom Elements and Shadow DOM APIs, and many implementations are well underway in major browsers.

Polymer currently relies on the v0 implementations of these APIs, which are also supported by the web components polyfills. Polymer will begin transitioning to these v1 APIs very soon. Components built with the current version of Polymer will still work even when browsers support v1 APIs natively, but will require the v0 polyfills. Upgrading components built with Polymer from the v0 APIs to v1 will be relatively straightforward, as Polymer already provides light abstractions over some of the more low-level, spec-specific details and will be able to handle the transition under the hood.

See Are We Componentized Yet? and caniuse.com for more information on native browser support for web components.

Notes:

  • Chrome natively implements the v0 APIs, and work is underway on the v1 APIs.

  • WebKit Nightly has a working implementation of Shadow DOM 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.