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

You're viewing an older version of the Polymer library documentation. Please see Polymer 3.0 for the latest.

EXPERIMENTAL: API MAY CHANGE.

Polymer is currently layered into 3 sets of features provided as 3 discrete HTML imports, such that an individual element developer can depend on a version of Polymer whose feature set matches their tastes/needs. For authors who opt out of the more opinionated local DOM or data-binding features, their element's dependencies would not be payload- or runtime-burdened by these higher-level features, to the extent that a user didn't depend on other elements using those features on that page. That said, all features are designed to have low runtime cost when unused by a given element.

Higher layers depend on lower layers, and elements requiring lower layers will actually be imbued with features of the highest-level version of Polymer used on the page (those elements would simply not use/take advantage of those features). This provides a good tradeoff between element authors being able to avoid direct dependencies on unused features when their element is used standalone, while also allowing end users to mix-and-match elements created with different layers on the same page.

  • polymer-micro.html: Polymer micro features (bare-minimum Custom Element sugaring)

  • polymer-mini.html: Polymer mini features (template stamped into "local DOM" and tree lifecycle)

  • polymer.html: Polymer standard features (all other features: declarative data binding and event handlers, property nofication, computed properties, and experimental features)

This layering is subject to change in the future and the number of layers may be reduced.

The Polymer micro layer provides bare-minimum Custom Element sugaring.

Feature Usage
Custom element constructor Polymer.Class({ … });
Custom element registration Polymer({ is: ‘...’, … }};
Custom constructor support constructor: function()
Basic lifecycle callbacks created, attached, detached, attributeChanged
Native HTML element extension extends: ‘…’
Declared properties properties:
Attribute deserialization to property properties:
Static attributes on host hostAttributes:
Behaviors behaviors: [ … ]

The Polymer mini layer provides features related to local DOM: Template contents cloned into the custom element's local DOM, DOM APIs and tree lifecycle.

Feature Usage
Template stamping into local DOM <dom-module><template>...</template></dom-module>
DOM distribution <content>
DOM API Polymer.dom
Configuring default values properties: <prop>:
Bottom-up callback after configuration ready: function()

The Polymer standard layer adds declarative data binding, events, property notifications and utility methods.

Feature Usage
Automatic node finding this.$.<id>
Event listener setup listeners:
Annotated event listener setup <element on-[event]=”function”>
Property change callbacks properties: <prop>:
Annotated property binding <element prop=”{{property|path}}”>
Property change notification properties: { <prop>:
Binding to structured data <element prop=”{{obj.sub.path}}”>
Path change notification set(<path>, <value>)
Declarative attribute binding <element attr$=”{{property|path}}”>
Reflecting properties to attributes properties: { <prop>:
Computed properties computed:
Computed bindings <span>{{computeFn(dep1, dep2)}}</span>
Read-only properties properties: { <prop>:
Utility functions toggleClass, toggleAttribute, fire, async, …
Scoped styling <style> in <dom-module>, Shadow-DOM styling rules (:host, ...)
General polymer settings <script> Polymer = { ... }; </script>