Polymer: the original Web Component library and how to use it

What Polymer solves, and who it is still for

Polymer is a library for defining custom HTML elements. The problem it addresses is that defining an element with the raw platform APIs means writing a class, registering it with customElements.define, wiring observed attributes to properties by hand, and managing the template and styles yourself. Polymer wraps that into a declarative form: you extend PolymerElement, declare a static properties getter that describes the public property and attribute API, and return an HTMLTemplateElement from a static template getter.

The README is direct about who this is no longer for. It notes that at Google I/O 2018 a new Web Component base class, LitElement, was announced as a successor to PolymerElement, and that if you are starting a new project the recommendation is to consider LitElement instead. So the honest audience is narrower than the library's history suggests: teams with an existing Polymer codebase, and teams that specifically want Polymer's two-way data binding rather than the one-way model LitElement uses.

The interoperability point is the one that keeps Polymer relevant in a mixed codebase. Because both libraries produce standard custom elements, elements built with Polymer 3.0 and LitElement can be mixed in the same app. That means migration can happen one element at a time rather than as a rewrite, which is the practical reason a Polymer project does not have to be abandoned wholesale.

How PolymerElement, templates and binding fit together

The mechanism is a class plus two static getters. The properties getter returns an object mapping property names to their types; the README states that these automatically become observed attributes. The template getter returns an HTMLTemplateElement built with the html tagged template literal, containing the element's markup, encapsulated styles, and property bindings.

Binding syntax is the visible surface of the library. In the README's minimal example, [[mood]] inside the template is replaced by the value of the mood property, so an element written as <my-element mood="happy"> renders the word happy inside a styled span. Polymer also offers optional two-way data binding, which the README describes as updating the element when the model's properties change.

The distribution model is the part that catches people out. Polymer 3.0 is published on npm using JavaScript Modules, so it relies on the native module loader present in current major browsers. But Polymer references dependencies by npm name, and browsers cannot resolve a bare specifier like @polymer/polymer to a URL on their own. A light transform that rewrites specifiers to URLs is therefore required. The polymer-cli development server and polymer build both perform that transform automatically; webpack and Rollup are named in the README as alternatives for serving or bundling. The library itself is a thin layer over platform primitives, and the package is small, but the toolchain around it is not optional if you want to run it in a browser.

Installing Polymer and defining your first element

The README recommends the Polymer CLI for local development. Add the library to your project first, then install the CLI globally, then run the development server with the --npm flag. The npm scripts in package.json also expose serve and test, where serve runs polymer serve --npm --module-resolution=node.

npm i @polymer/polymer
npm i -g polymer-cli
polymer serve --npm

After polymer serve --npm starts, the README says to open a browser pointing at the URL it prints. That server is what rewrites the npm specifiers into URLs the browser can load, so opening the files directly from disk will not work for a project with npm dependencies.

The element itself is a module that imports PolymerElement and html from @polymer/polymer, extends PolymerElement, declares properties, returns a template, and registers the tag with customElements.define. The README's example loads the webcomponents-loader polyfill first and then the module script.

<script src="node_modules/@webcomponents/webcomponents-loader.js"></script>
<script type="module">
  import {PolymerElement, html} from '@polymer/polymer';

  class MyElement extends PolymerElement {
    static get properties() { return { mood: String }}
    static get template() {
      return html`
        <style> .mood { color: green; } </style>
        Web Components are <span class="mood">[[mood]]</span>!
      `;
    }
  }

  customElements.define('my-element', MyElement);
</script>

<my-element mood="happy"></my-element>

If you only want to try the library before setting up a project, the README points at online sandboxes instead: StackBlitz and Glitch for all supported browsers, and JSBin or CodePen for browsers with JavaScript Modules. It also links a single HTML file you can save locally and open in any browser with module support, which is the fastest way to see the binding syntax work.

Where Polymer stops being the right tool

The clearest limitation is stated by the project itself: for new work, the README recommends considering LitElement rather than PolymerElement. That is not a subtle deprecation notice buried in a changelog; it sits at the top of the README. Choosing Polymer for a greenfield project means choosing a base class the maintainers have already positioned as a predecessor.

The second constraint is the module transform. Because Polymer uses npm conventions to reference dependencies by name, a plain static file server will not resolve those imports. You need polymer serve, polymer build, webpack, or Rollup in the path. That is a real cost for anyone who wanted a component library they could drop onto a CDN-hosted page without a build step.

The third is browser support. The README describes Web Components as implemented natively on Safari and Chrome at roughly 70% of installed browsers at the time of writing, with Firefox, Edge, and IE11 running them well through polyfills. That percentage is from the README and is dated; the point that survives is that supporting older browsers means shipping the webcomponentsjs loader, which adds a dependency and a load-order requirement that the example above demonstrates with a plain script tag before the module script.

A fourth is the release cadence. The most recent release listed is v3.5.2 from 2024-10-07, and the two before it are v3.4.1 and v3.4.0 from April 2020. The repository's last push was on 2026-04-02. A library whose minor releases are years apart is one where you should expect to fix your own problems rather than wait for an upstream patch.

LitElement and Polymer compared by approach

The real alternative is LitElement, which the README names as the successor to the PolymerElement base class. The difference is not cosmetic. Polymer's template getter returns an HTMLTemplateElement and the library maintains a binding system on top of it, including the optional two-way binding the README highlights. LitElement, as described in the README, is a Web Component base class; the README positions it as where new projects should go and notes that the two can coexist in one application.

That coexistence is the practical migration path. Because Polymer 3.0 elements and LitElement elements are both standard custom elements, they can be mixed and matched, so a team can convert one element at a time rather than stopping work to port everything. The README explicitly recommends migrating an earlier Polymer project to 3.0 first for best compatibility with the JavaScript ecosystem, and then moving to LitElement incrementally.

If your constraint is not the base class but the build step, the alternatives named in the README are webpack and Rollup for serving or bundling Polymer elements. Those do not replace Polymer; they replace the polymer-cli transform, which matters if you already have a bundler configured and do not want a second toolchain.

Licence, maintenance and upgrade cost

Polymer is published under BSD-3-Clause, and the repository contains a LICENSE.txt at the top level. That is a permissive licence, which generally means you can use, modify, and redistribute the library including in commercial products, provided the copyright notice and licence text are retained. This is a description of the licence identifier, not legal advice; if your organisation has specific redistribution or patent concerns, have counsel read LICENSE.txt rather than relying on the identifier alone.

Maintenance is best judged from the repository facts rather than the project's reputation. The last push was on 2026-04-02, and the latest release is v3.5.2 from 2024-10-07. The gap between v3.4.0 in April 2020 and v3.5.2 in October 2024 tells you more about the project's rhythm than any statement about its health. Expect long periods without releases.

Upgrade cost depends on which version you are on. The README's guidance is to migrate an earlier Polymer project to 3.0 for compatibility with the JavaScript ecosystem, and it frames that migration as a prerequisite for moving to LitElement later. The 3.0 line is also where the npm and JavaScript Modules distribution model applies, so a pre-3.0 project is not just a version bump; it is a change in how dependencies are referenced and loaded. Budget for the module specifier rewrite and the toolchain that performs it, not just for API renames.

Editorial conclusion

Adopt Polymer if you maintain an existing Polymer codebase or need its two-way data binding and declarative property/attribute mapping today. Do not start a new project on it: the README points new projects to LitElement. Before committing, verify that your target browsers support JavaScript Modules natively or that you are prepared to load the webcomponents-loader polyfill, and check that your build toolchain handles the npm specifier rewrite that polymer serve and polymer build perform.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Polymer/polymer on GitHub
3. Project website
4. README
5. Releases