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

Polymer 3.0 is the latest version of the Polymer library for building web components.

Polymer 3.0 represents a simple but important step forward from Polymer 2.x: Polymer 3.0 has moved from HTML Imports to ES6 Modules, and from Bower to npm. These changes represent a move toward the mainstream of JavaScript development, making it easier to use Polymer (and Polymer-based elements) with other popular libraries, frameworks and tools.

Here's a quick sample of defining an element in Polymer 3.0:

likeable-element.js
// Import an element
import '@polymer/paper-checkbox/paper-checkbox.js';

// Import the PolymerElement base class and html helper
import {PolymerElement, html} from '@polymer/polymer';

// Define an element class
class LikeableElement extends PolymerElement {

  // Define public API properties
  static get properties() { return { liked: Boolean }}

  // Define the element's template
  static get template() {
    return html`
      <style>
        .response { margin-top: 10px; } 
      </style>
      <paper-checkbox checked="{{liked}}">I like web components.</paper-checkbox>

      <div hidden$="[[!liked]]" class="response">Web components like you, too.</div>
    `;
  }
}

// Register the element with the browser
customElements.define('likeable-element', LikeableElement);
  

index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="./node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
    <script src="./node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
  </head>
  <body>
    <likeable-element></likeable-element>
  </body>
</html>

Related product. For new development, you should consider LitElement, a light, performant, next-generation base class for custom elements.

The Polymer 3.0 API is almost 100% backward compatible with Polymer 2.x—the only changes are removing APIs related to HTML Imports (such as importHref), and converting Polymer's API to be module-based rather than globals-based.

API reference

Like we did for the Polymer 1.x-to-2.0 transition, we've made a smooth upgrade path our top priority for Polymer 3.0. Polymer's API remains almost unchanged, and we're providing an upgrade tool (polymer-modulizer) that will automatically handle most of the work in converting your 2.x-based elements and apps to 3.0.

Upgrade guide

With the 3.0 release, we'll be updating not just the core Polymer library, but all of the various resources we provide for building elements and apps with web components:

  • The Polymer CLI and associated tools have been updated to support developing, testing and deploying projects composed of ES Modules.

  • The Polymer Starter Kit and other app and element templates included with the CLI have been converted to use modules.

  • The web component polyfills have been updated.

  • The Polymer Elements, like the core library, have been converted to ES Modules and published to npm. The elements are currently in pre-release, and must be installed with the @next version:
    npm i @polymer/paper-button@next

    Final 3.0.0 versions of the elements will be published soon.

In sum, the goal of Polymer 3.0 is to make sure that anyone who has built elements and apps with earlier versions of Polymer (or following patterns and conventions established by Polymer) can easily move to the new version.

The easiest way to try out Polymer is to use an online code editor. The following templates will get you started. The first two editors run code in all supported browsers:

You can also use the following editors, but the code only runs on browsers that support ES6 modules:

You can also save this HTML file to a local file and run it in any browser that supports ES6 modules.

See Try Polymer to try out some of Polymer's features. Once you're ready to try out Polymer 3.0 in a project, you can install it using npm. See Install 3.0 for details.