@polymer/polymer

What is @polymer/polymer?

@polymer/polymer is a library for building web components using the Polymer framework. It provides a set of features to create reusable, encapsulated HTML elements with custom behavior.

What are @polymer/polymer's main functionalities?

Define a Custom Element

This feature allows you to define a custom HTML element with specific properties and behaviors. The example shows how to create a custom element named 'my-element' with a property 'myProperty'.

class MyElement extends Polymer.Element {
  static get is() { return 'my-element'; }
  static get properties() {
    return {
      myProperty: {
        type: String,
        value: 'default value'
      }
    };
  }
}
customElements.define(MyElement.is, MyElement);

Data Binding

This feature allows you to bind data to your custom element's template. The example shows how to bind the 'myProperty' value to a div inside the custom element's template.

<dom-module id="my-element">
  <template>
    <div>{{myProperty}}</div>
  </template>
  <script>
    class MyElement extends Polymer.Element {
      static get is() { return 'my-element'; }
      static get properties() {
        return {
          myProperty: {
            type: String,
            value: 'default value'
          }
        };
      }
    }
    customElements.define(MyElement.is, MyElement);
  </script>
</dom-module>

Event Handling

This feature allows you to handle events within your custom element. The example shows how to handle a click event on a button inside the custom element's template.

<dom-module id="my-element">
  <template>
    <button on-click="handleClick">Click me</button>
  </template>
  <script>
    class MyElement extends Polymer.Element {
      static get is() { return 'my-element'; }
      handleClick() {
        console.log('Button clicked');
      }
    }
    customElements.define(MyElement.is, MyElement);
  </script>
</dom-module>

Other packages similar to @polymer/polymer

lit-element

LitElement is a simple base class for creating fast, lightweight web components. It uses lit-html to render templates and provides a reactive property system. Compared to @polymer/polymer, LitElement is more lightweight and has a smaller API surface.

stencil

Stencil is a compiler that generates Web Components and builds high-performance web apps. It combines the best concepts of the most popular frameworks into a simple build-time tool. Stencil is more focused on performance and modern web standards compared to @polymer/polymer.

skatejs

SkateJS is a library for building web components that focuses on being small and performant. It provides a simple API for defining custom elements and managing their lifecycle. SkateJS is more minimalistic and performance-oriented compared to @polymer/polymer.

README

Polymer

ℹ️ Note: This is the current stable version of the Polymer library. At Google I/O 2018 we announced a new Web Component base class, LitElement, as a successor to the PolymerElement base class in this library.

If you're starting a new project, we recommend that you consider using LitElement instead.

If you have a project you've built with an earlier version of the Polymer library, we recommend that you migrate to 3.0 for best compatibility with the JavaScript ecosystem. Thanks to the interoperability of Web Components, elements built with Polymer 3.0 and LitElement can be mixed and matched in the same app, so once you have updated your project to Polymer 3.0, you can migrate to LitElement incrementally, one element at a time. See our blog post on the Polymer Project roadmap for more information.

Polymer lets you build encapsulated, reusable Web Components that work just like standard HTML elements, to use in building web applications. Using a Web Component built with Polymer is as simple as importing its definition then using it like any other HTML element:

<!-- Import a component -->
<script src="https://unpkg.com/@polymer/paper-checkbox@next/paper-checkbox.js?module" type="module" ></script>

<!-- Use it like any other HTML element -->
<paper-checkbox>Web Components!</paper-checkbox>

Web Components are now implemented natively on Safari and Chrome (~70% of installed browsers), and run well on Firefox, Edge, and IE11 using polyfills. Read more below.

Getting started

• The easiest way to try out Polymer is to use one of these online tools:

  • Runs in all supported browsers: StackBlitz, Glitch

  • Runs in browsers with JavaScript Modules: JSBin, CodePen.

• You can also save this HTML file to a local file and run it in any browser that supports JavaScript Modules.

• When you're ready to use Polymer in a project, install it via npm. To run the project in the browser, a module-compatible toolchain is required. We recommend installing the Polymer CLI to and using its development server as follows.

  1. Add Polymer to your project:

     npm i @polymer/polymer

  2. Create an element by extending PolymerElement and calling customElements.define with your class (see the examples below).

  3. Install the Polymer CLI:

     npm i -g polymer-cli

  4. Run the development server and open a browser pointing to its URL:

     polymer serve --npm

  Polymer 3.0 is published on npm using JavaScript Modules. This means it can take advantage of the standard native JavaScript module loader available in all current major browsers.

  However, since Polymer uses npm conventions to reference dependencies by name, a light transform to rewrite specifiers to URLs is required to run in the browser. The polymer-cli's development server polymer serve, as well as polymer build (for building an optimized app for deployment) automatically handles this transform.

  Tools like webpack and Rollup can also be used to serve and/or bundle Polymer elements.

Minimal Example

1. Create a class that extends PolymerElement.
2. Implement a static properties getter that describes the element's public property/attribute API (these automatically become observed attributes).
3. Then implement a template getter that returns an HTMLTemplateElement describing the element's rendering, including encapsulated styling and any property bindings.

  <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>

Overview

Web components are an incredibly powerful new set of primitives baked into the web platform, and open up a whole new world of possibility when it comes to componentizing front-end code and easily creating powerful, immersive, app-like experiences on the web.

Polymer is a lightweight library built on top of the web standards-based Web Components APIs, and makes it easier to build your very own custom HTML elements. Creating reusable custom elements - and using elements built by others - can make building complex web applications easier and more efficient.

By being based on the Web Components APIs built in the browser (or polyfilled where needed), elements built with Polymer are:

• Built from the platform up
• Self-contained
• Re-usable
• Interoperable across frameworks

Among many ways to leverage custom elements, they can be particularly useful for building reusable UI components. Instead of continually re-building a specific navigation bar or button in different frameworks and for different projects, you can define this element once using Polymer, and then reuse it throughout your project or in any future project.

Polymer provides a declarative syntax to easily create your own custom elements, using all standard web technologies - define the structure of the element with HTML, style it with CSS, and add interactions to the element with JavaScript.

Polymer also provides optional two-way data-binding, meaning:

1. When properties in the model for an element get updated, the element can update itself in response.
2. When the element is updated internally, the changes can be propagated back to the model.

Polymer is designed to be flexible, lightweight, and close to the web platform - the library doesn't invent complex new abstractions and magic, but uses the best features of the web platform in straightforward ways to simply sugar the creation of custom elements.

About Polymer 3.0

Polymer 3.0 is now released to stable, and introduces a major change to how Polymer is distributed: from HTML Imports on Bower, to JS modules on npm. Otherwise, the API is almost entirely backward compatible with Polymer 2.0 (the only changes are removing APIs related to HTML Imports like importHref, and converting Polymer's API to be module-based rather than globals-based).

Migrating to Polymer 3.0 by hand is mostly mechanical:

• Components should be defined in JS modules instead of in HTML
• Templates should be encoded in JS modules using a static get template() getter on PolymerElement subclasses using the html tagged template literal function (which parses HTMLTemplateElements out of strings in JS) rather than using <template> elements in a <dom-module>
• All dependencies should be imported JS module imports rather than HTML Imports.

However, the polymer-modulizer tool automates the vast majority of this migration work. Please see details on that repo for automated conversion of Polymer 2.0 apps and elements to Polymer 3.0.

👀 Looking for Polymer v2.x? Please see the the v2 branch.

👀 Looking for Polymer v1.x? Please see the the v1 branch.

Contributing

The Polymer team loves contributions from the community! Take a look at our contributing guide for more information on how to contribute. Please file issues on the Polymer issue tracker following the issue template and contributing guide issues.

Communicating with the Polymer team

Beyond GitHub, we try to have a variety of different lines of communication available:

• Blog
• Twitter
• Google+ community
• Mailing list
• Slack channel

License

The Polymer library uses a BSD-like license that is available here

Changelog

v3.2.0 (2019-03-21)

• [ci skip] update polymer version (commit)

• Fix lint (commit)

• Add tests. (commit)

• Ensure debouncer is removed from queue before running callback. (commit)

• Don't clear set at end for flush reentrancy safety; canceling removes from set (commit)

• Assert the callback was called. (commit)

• Ensure the debouncer is not already canceled before canceling. (commit)

• Fix a couple of closure type issues. * gestures - update internal type changes * debounce - fix mistaken return type (commit)

• Revert to getStyle() (commit)

• Fix getStyle definition (commit)

• Add extra test (commit)

• Use in check rather than undefined. (commit)

• Allow value to merge from previous behavior property declaration. Fixes #5503 (commit)

• Fix/suppress upcoming JSCompiler build errors (commit)

• Add comment about flush order when re-debouncing (commit)

• FIx lint (commit)

• Remove debug code (commit)

• Re-add the queue removal in setConfig (commit)

• Remove debug code (commit)

• Remove test.only (commit)

• Fix order of flushed debouncers to match 1.x (commit)

• Add comments and avoid Array.fill (commit)

• Use set and clear debouncer upon completion. Fixes #5250. (commit)

• Added comment based on review feedback. (commit)

• Add property reflection to notify path and friends calls to support closure-compiler renaming. (commit)

• Add classList to Polymer.dom when ShadyDOM.noPatch is used (commit)

• Update externs from internal (commit)

• Use webcomponents 2.2.7 for initialSync tests (commit)

• Add @fileoverview, put @suppress after it (commit)

• address feedback (commit)

• use JSCompiler_renameProperty bare (commit)

• Remove semicolon after class definition (lint). (commit)

• Refactor symbols to make gen-typescript-declarations happy (commit)

• Ensure argument types match. (commit)

• Backport closure compiler fixes from internal (commit)

• Fix test warning in Edge/IE (commit)

• Fix test in IE/Edge (commit)

• Update package-lock (commit)

• Update webcomponents vesrion. (commit)

• Remove unused import (commit)

• Add comment re: undefined issue (commit)

• Move undeclared property warning to element-mixin. (commit)

• Add issue for TODO (commit)

• Upgrade wcjs (commit)

• Fix lint errors. (commit)

• Upgrade wcjs (commit)

• Updates based on review. (commit)

• Add better messaging for scoping test (commit)

• Remove addressed TODO comment. (commit)

• Clarify warning. Add comment. (commit)

• Add warnings for disabling boolean settings. (commit)

• Upgrade webcomponentsjs (commit)

• Upgrade webcomponentsjs (commit)

• Refactor to make code more readable, add tests, remove dead code. (commit)

• Adds syncInitialRender setting (commit)

• Ensure that marshalArgs pulls wildcard info value from __data It currently pulls the value from changedProps rather than __data, meaning it could provide stale data for re-entrant changes. (commit)

• Fix lint warning (commit)

• Add warning for redeclared computed properties. (commit)

• Add warning for undeclared properties used in bindings. (commit)

• Make initial distribution synchronous when legacyOptimizations is set (commit)

• Ensure dispatchEvent is wrapped (commit)

• Disable auto strip-whitespace on template with legacyOptimizations (commit)

• Add tests for calling Polymer() with ES6 class (commit)

• use a regular for-loop intead of for-of (commit)

• Lint clean (commit)

• Remove @override from static methods on mixins. (commit)

• Externs should use var instead of let (commit)

• Add @suppress annotations for missing property checks. (commit)

• Allow Polymer({}) calls with ES6 class (commit)

• [wrap] Fix doc comment. (commit)

• Fix typo (commit)

• Make sure _valueToNodeAttribute uses wrap (commit)

• Suppress upcoming jscompiler errors. (commit)

• compromise with typescript and closure (commit)

• Closure typing fixes (commit)

• Add type jsdoc to templatize root property. (commit)

• Remove meaningless "undefined" in settings.js (commit)

• Make noPatch safe with older versions of ShadyDOM (commit)

• Temporarily disable type genration (commit)

• Changes based on review. (commit)

• Changes based on review. (commit)

• More shady compatible wrapping (commit)

• Fix typos (commit)

• Update to match 2.x branch (commit)

• Revert "Manual merge from perf-opt-disable-upgrade branch." (commit)

• Update Polymer 3 package-lock. (commit)

• Update to webcomponentsjs 2.2.0 (commit)

• Update to latest webcomponentsjs (commit)

• Manual merge from perf-opt-disable-upgrade branch. (commit)

• Remove double-import of settings (commit)

• Document properties for eslint. (commit)

• Add back event tests. (commit)

• Use closure-safe name (commit)

• Add tests (commit)

• Ensure properties and observers are interleaved per behavior (commit)

• Ensure property values are always overridden by extendors/behaviors (commit)

• Ensure registered is always called on element prototype (commit)

• err instead of air (commit)

• Do lazy behavior copying only when legacyOptimizations is set (commit)

• Behavior property copying fixes (commit)

• Ensure initial static classes are preserved when a class$ binding is present (commit)

• Get typescript compiling again. (commit)

• Remove extra space (commit)

• Avoid copying certain properties from behaviors (commit)

• skip some tests that never really worked in ShadyDOM (commit)

• Move __activateDir into check instead of replace (commit)

• Don't set up observer in ShadyDOM (commit)

• Manually merge changes from #5418 (commit)

• Fix merge conflict around toggleAttribute (commit)

• Get Polymer compiling clean under closure recommended flags (commit)

• Apply LegacyDataMixin to TemplatizeInstanceBase. Fixes #5422 (commit)

• TemplateStamp (commit)

• Fixes #5420 (commit)

• Lint fix (commit)

• Updates ported from perf-opt branch (commit)

• rename test file. (commit)

• Check for ShadyDOM and :dir selectors before trying css transform (commit)

• Rename Closure V1 compatibility PolymerDomApi types for TypeScript types. (commit)

• Hybrid compatibility for PolymerDomApi and Polymer.Iconset types. (commit)

• Fix another unsafe property assignment in Polymer. (commit)

• Add explicit null template for array-selector (commit)

• remove cruft (commit)

• Adds basic legacy support for ShadyDOM.unPatch (WIP) (commit)

• [ci skip] update changelog (commit)

• Adds setting to skip style incudes and url rewriting (commit)

• restores functionality of Polymer.mixinBehaviors (commit)

• Avoids using mixins for behaviors. (commit)

• Fix jsdoc comment (commit)

• Upstream warning text. (commit)

• Upstream changes to externs (commit)