Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Our original Web Component library.

Subscribe to updates I use polymer

Statistics on polymer

Number of watchers on Github 21434
Number of open issues 276
Average time to close an issue 5 days
Main language HTML
Average time to merge a PR 4 days
Open pull requests 195+
Closed pull requests 48+
Last commit 4 months ago
Repo Created about 8 years ago
Repo Last Updated 3 months ago
Size 29.4 MB
Homepage https://polymer-l...
Organization / Authorpolymer
Latest Releasev3.4.1
Page Updated
Do you use polymer? Leave a review!
View open issues (276)
View polymer activity
View on github
Book a Mock Interview With Me (Silicon Valley Engineering Leader, 100s of interviews conducted)
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating polymer for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Build Status Published on npm Published on webcomponents.org

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:

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

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

1. Install the Polymer CLI:

    ```npm i -g polymer-cli```

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

    ```polymer serve --npm```

> Polymer 3.0 is published on [npm](https://www.npmjs.com/package/@polymer/polymer) 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](https://webpack.js.org/) and [Rollup](https://rollupjs.org/) 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);

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


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.


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:


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

polymer open issues Ask a question     (View All Issues)
  • almost 4 years attributeChanged event not firing in Firefox
  • almost 4 years tap event not dispatched unless listener specified in polymer definition
  • almost 4 years Support DOMTokenList-style attribute values for type:Array properties
  • almost 4 years Component Model
  • almost 4 years Expose hooks for setting values to dom
  • almost 4 years Implement build time optimizations
  • almost 4 years `dom-repeat` inside `table` element is having unexpected behavior in 2.0 preview
  • almost 4 years Registration failed for type 'dom-module'/DuplicateDefinitionError: a type with name 'dom-module' is already registered
  • almost 4 years Latest Crome Issues
  • almost 4 years Update `importHref` in 2.x-preview branch to match implementation in master
  • almost 4 years Documentation Not working for Polymer 2.0 / Native Web Components
  • almost 4 years 2.0-preview error in composition of css mixins
  • almost 4 years Support dynamic property binding names
  • almost 4 years 2.0 - Load order importance when using style mixins
  • almost 4 years Text nodes are not distributed to default slot
  • almost 4 years Discourage using ready callback 2.x
  • almost 4 years Wrong usage of Polymer.RenderStatus.afterNextRender in the upgrade guide
  • almost 4 years Add Polymer.Element class for Hybrid mode
  • almost 4 years Errors in 2.0 child element templating
  • almost 4 years Warn on `this.listen` and `this.unlisten` calls if `node` argument does not exist
  • almost 4 years Polymer 2.0 : Error.
  • almost 4 years `connectedCallback` not called after creating a tree with `Polymer.dom(..)` methods when using Shady DOM.
  • almost 4 years Docs not clear on setting readOnly private properties
  • almost 4 years Binded slot name do not distribute content as expected in Polymer#1.7.0
  • about 4 years Refactor binding regex to small scanner to allow custom expressions to be defined
  • about 4 years Get the original DOM event from track gesture event
  • about 4 years Simple observer on array property receives 'length' values
  • about 4 years Templatizer refactoring
  • about 4 years Polymer.dom.flush in 2.x does not flush what it did in 1.x
  • about 4 years Consider ways to remove path work from hot paths
polymer open pull requests (View All Pulls)
  • Fix undefined class attribute in undefined template scope
  • Reduce domif performance overhead
  • Refactorings around how computational expressions get their arguments
  • Enforce undefined rule for observers
  • Non developer readme contribution
  • Purpose readme contribution
  • Namespace support (a.k.a. SVG handling)
  • Allow listeners to be defined by function (not just by name)
  • Fix merging of property metadata
  • Implement method for dirty-checking of properties
  • Better handling and error msgs for registration oopsies
  • Perform element registration tasks at first instance creation rather than registration time
  • Extends plus set object array
  • Only test builds on travis
  • Make notifyPath's value argument optional.
  • Null debounced callback to set for GC.
  • Expose bare minimum to add effects dynamically.
  • Loosen undefined rule for computational expressions
  • Cache length of c$
  • Remove dirty checks for objects
  • Assume attribute changes as coming from above.
  • Ensure fromAbove for downwards bindings.
  • Ensure fromAbove in _forwardParentProp.
  • Run each effect exactly once during config
  • Shim CSS Mixins in terms of CSS Custom Properties
  • Rename index.html to index.html
  • Fix nextSibling after appendChild
  • Let read-only properties participate in upwards flowing data.
  • Allow setting read-only properties using `set`
  • Lazy register extends
  • Bare minimum for custom effects (take 2)
  • Prevent tap from firing after a 300ms long touch.
  • Implement initialization guard for computed expressions
  • Support array path format for linkPaths() and unlinkPaths()
  • Upwards notifications should not echo downwards
  • Implement linkPath as (custom) property effect.
  • Add an escape sequence to avoid polymer to bind the content of brackets
  • `use strict`ify closured Polymer source
  • Include iron-component-page in devDependencies
  • Replace the suffix '-changed' by Polymer.Base._EVENT_CHANGED
  • Strawman for `setMultipleProperties`
  • Fix 3637,3638
  • Expose a Path module/library
  • Fix _patchMatchesEffect.
  • Fix conditions when dom-repeat needs to re-sort or re-filter.
  • Use property effects to notify path changes upwards
  • Ensure custom styles updated after adding custom-style async. Fixes #3705.
  • Update .polymer
  • fix-binding undefined value of property
  • Improve type signatures: `Polymer.Base.extend` and `Polymer.Base.mixin`
  • Fixes #3676: retain <style in <template preserve-content/>
  • Fix for changing property to the same value
  • Allow more whitespace in style include attribute
  • Fixes #3739: correctly shim `:host(.element-name)` as `element-name.eā€¦
  • DRY on same code
  • Even lazier, lazyRegister
  • Replace VAR_MATCH regex with a simple state machine / callback
  • Ensure properties override attributes at upgrade time. Fixes #3779.
  • Fix a typo in dom-if.html.
  • Refresh cache'd styles contents in IE 10 and 11
  • Set latest firefox addon for testing
  • Better error message for bad listeners entry.
  • add importHref listeners to non-cached imports
  • Allow dom-repeat for array-like Objects
  • Fix for leaking taps, fixes #3704
  • Use this instead of self.
  • Update the CSS transforms to allow colons within Simple Selectors.
  • Do notify once per property at most
  • Be more precise about the origin of webcomponentsjs
  • Variables invalid at compute time should have the value of "unset"
  • Remove guard for iOS/Android in ignoreMouse
  • Do not parse bindings inside script tags
  • Fix binding to field in object with slash in key name
  • Clear paths upon object invalidation. Fixes #3998.
  • Queue accessor value on instance. Fixes #4044.
  • Fix rootDataHost. Add templatizer tests. Rename to Templatizer.flush.
  • Add property argument to `_shouldPropChange`.
  • Exclude custom template elements from search for cssFromElement().
  • 3430 - ie memory leak fixes - disable event caching, fixed resolver uā€¦
  • TypeScript decorators for defining Polymer elements
  • Prevent _showHideChildren from being called on placeholders.
  • Fixes #4084: distribution on binded slot name.
  • Move importHref to Polymer.Utils, facade to LegacyElement. Fixes #4045
  • Move resolveUrl to Polymer.Element, get `is` from ctor. Fixes #3992
  • Refactor dom-if & dom-repeat using Polymer.Element.
  • Upgrade shorthand type to {type:Type} when flattening. Fixes #4066.
  • Look for `_template` in legacy API's template getter. Fixes #4078.
  • Minor feature additions/improvements
  • [2.x] Move Firefox testing to sauce (windows), to test with latest Firefox
  • dynamic-import `importHref()` callback fix when the same resource is requested multiple times
  • Add Polymer.Element base class
  • Dom-repeat... fixed when to throw message about absent template
  • Update PRIMER.md
  • 2.0 preview: extending templates
  • Don't flush props if props aren't passed
  • Introduce new API for `debouncer` and `Async`
  • Close backtick in ISSUE_TEMPLATE.md
  • Make Polymer 2.0 compatible with Closure Compiler
  • depends on test-fixture ^2.0.1
  • Test with more browsers on saucelabs
  • fix README.md
  • Error thrown when creating Events with IE11 Polyfill
  • Clicks on labels don't check their corresponding inputs
  • 3336 use classList.add to avoid duplicate classes
  • šŸ’šŸ’°šŸ”§ (DO NOT MERGE)
  • Refactor importHref
  • More practical caching strategy for importHref
  • Fix for #4150
  • Observer property pass
  • Fix unreadable logging in dark theme Chrome console
  • Ensure no warnings for dynamic fns. Fixes #4575
  • Corrected minor Method comments
  • Support property observers which are direct function references
  • Jsdoc new tags
  • Copying bower -> package.json to allow for yarn installations
  • fixes lib/utils/gestures.html for gulp-eslint
  • test more permutations
  • fixed Polymer.importHref without native HTMLImports
  • suggesting slight verbiage changes for the intro paragraph
  • [2/2] Add keywords
  • [1/2] Add keywords
  • Use BSD-3-Clause as license
  • Add homepage to bower.json
  • Use https://www.polymer-project.org as homepage
  • Exclude package.json file from Bower package
  • WIP: First attempt at generated TypeScript declarations. Not there yet.
  • Adds `restamp` mode to dom-repeat.
  • Improve importHref()
  • Support semicolons in quotes and parenthesis in custom property values
  • Upgrade babel-preset-babili
  • Not an RC anymore
  • Fix typo in prop of FlattenedNodesObserver
  • Vend mixins for listeners block and hostAttributes block
  • fix ArraySplice @types to more closely match code
  • Update custom-style.html
  • Minor Comment Update
  • Upgrade WCT
  • Update gitignore file
  • use wct 6
  • Move shadycss and webcomponentsjs from dev-deps to deps
  • Change 'Polymer Project Authors' to 'Polymer Authors'
  • Use javascript string escaping in Polymer.html
  • Simplify code for <dom-repeat>'s `sort` and `filter` properties
  • Delete package-lock.json
  • Fix issue where el.splice could not clear full array
  • [WIP] Correct field type declarations
  • Fix label tap by checking matched label pairs
  • Allow templatizer to be used without owner or host prop forwarding. Fixes #4458
  • Disallow non-templates as interpolations in Polymer.html
  • [1.x] Allow adding type="custom" to avoid deprecation warning. Fixes #5017
  • [2.x] Allow adding type="custom" to avoid deprecation warning. Fixes #5017
  • Adds `Polymer.DisableUpgradeMixin`
  • Templatize: remove slots when hiding children
  • improve README.md
  • Remix'd #4363
  • Array-selector batch selection
  • Fix issue when bindings were updated when dom-if was false
  • dom-repeat: add filteredItemCount to display total count of items with filter applied
  • Clarify API docs for PropertyAccessors mixin
  • Change findTemplateNode to work on array of indices
  • Fix #4818
  • Support ES6 getters and setters for data binding
  • Rewrite expression parser to a state machine in optional mixin
  • Set mutableData to true in MutableData mixin
  • Use stronger check for PropertyEffects clients. Fixes #5107
  • Remove unneeded file
  • Fix license links
  • Add CodeTriage badge to polymer/polymer
  • Throw an error if Polymer is loaded twice
  • Add mixin to automatically detect capitalized HTML attributes
  • Add instructions for locally viewing the source documentation
  • Add note to updateStyles regarding updates to CSS mixins
  • Update property-effects.html - Add support for promises.
  • Evaluated computed property dependencies first. Fixes #5143
  • Make dom-elements work inside svgs
  • Loosen _attachDom return signature.
  • Create jekyll.yml
  • Stop forcing the custom elements polyfill in tests.
  • Update the polyfills; fix a type generation error.
  • Prevent dom-repeat's forwardHostProp from retaining HTMLElement `this`
  • Add support for ShadyDOM on-demand patching
  • Consolidate imports
  • Read the CSS build type at the first instance creation rather than at registration time.
  • Only consider a class "registered" when it is the top-most prototype
  • Remove use of TreeWalker for finding nodes in templates.
  • Fix a couple of minor typos.
  • Fix case map
  • Changes to make compatible with `noPatch` version of ShadyDOM [2.x]
  • Avoid initializing properties unnecessarily (perf benefit), alternate. [2.x]
  • Improve support for`disable-upgrade` [2.x]
  • Avoid initializing properties unnecessarily (perf benefit). [3.x]
  • Avoid initializing properties unnecessarily (perf benefit). [2.x]
  • Add tests with polymer-css-build
  • Port externs update from internal changes
  • Adding support for data uris in resolveUrl.
polymer questions on Stackoverflow (View All Questions)
  • How to use polymer in rails using bow-rails
  • Computed binding doesn't work with on-click (Polymer)
  • Polymer 1.0 app routing, load external pages inside div
  • How to autofocus/autoclick paper-input in polymer 1.0?
  • polymer focus() on <paper-input> or <core-input> element
  • Polymer, issue with binding array to paper slider max value
  • Updating a polymer element property with data from API call
  • PageJs pretty URLs in Polymer aren't working
  • Polymer compute and set property value with this.set() not working
  • (generator-polymer) yo polymer fails, cannot find module 'find-index'
  • Need guide for Polymer + Material Design Lite
  • Using datalist from local DOM in polymer
  • Can I dynamically change a Polymer iron-flex-layout (flexbox) based on media query
  • Assigning url property to Polymer iron-ajax only works in Blink browsers
  • Hidden attribute in Polymer 1.0
  • How to implement error tracking in a polymer?
  • GWT Polymer material design
  • Polymer 1.0 two-way binding to an Array change event not firing
  • Polymer Iron-Form response
  • How to deploy Polymer 1.0 to ubuntu 14.04?
  • Add Polymer on Sails.js
  • Polymer background not extending to child elements in IE11
  • Div responsive equivalent in polymer?
  • Polymer elements overlaying photoswipe on iOS
  • Polymer inline JavaScript not working in IE 11
  • Polymer custom-row-style in paper-datatable
  • Polymer paper element attributes and Angular2
  • Pass data into a Polymer element without using polymer
  • Polymer, binding to array items not working
  • Polymer Elements don't work with latest GWT2.8 SNAPSHOT
polymer list of languages used
polymer latest release notes
v3.4.1 v3.4.1
  • [ci skip] bump to 3.4.1 (commit)

  • Add type for DomApiNative's setAttribute method. (commit)

  • Remove gen-typescript-declarations; manually add LegacyElementMixin's setAttribute type. (commit)

  • Remove DO NOT EDIT warning comments. (commit)

  • Track TypeScript declarations. (commit)

  • Update Closure types for overridden setAttribute in LegacyElementMixin. (commit)

  • Add method / parameter descriptions. (commit)

  • Fix TypeScript breakages by specifying types for overridden setAttribute and getAttribute. (commit)

  • Add complete commit list for v3.4.0 (commit)

  • Fix a couple more compiler warnings (commit)

  • Typos and other minor changes. (commit)

  • Add a note about a bug fix for chunking. (commit)

  • Add useAdoptedStyleSheetsWithBuiltCSS section. (commit)

  • Add setters to settings titles. (commit)

  • Add a note about orderedComputed and cycles. (commit)

  • Add example of overriding suppressTemplateNotifications via notify-dom-change. (commit)

  • Add a section about automatic use of constructable stylesheets. (commit)

  • Add Other new features section for reuseChunkedInstances and LegacyElementMixin's built-in disable-upgrade support. (commit)

  • Added notes for fastDomIf, removeNestedTemplates, suppressNestedTemplates, and suppressTemplateNotifications. (commit)

  • Started on release notes for legacyUndefined, legacyWarnings, orderedComputed. (...) (commit)

  • Remove unused externs. (commit)


v3.4.0 v3.4.0

New global settings

This update to Polymer includes some new global settings:

  • legacyUndefined / setLegacyUndefined

What does it do? This setting reverts how computed properties handle undefined values to the Polymer 1 behavior: when enabled, computed properties will only be recomputed if none of their dependencies are undefined.

Components can override the global setting by setting their _overrideLegacyUndefined property to true. This is useful for reenabling the default behavior as you migrate individual components:

  import {PolymerElement, html} from '@polymer/polymer/polymer-element.js';
  class MigratedElement extends PolymerElement { /* ... */ }
  // All MigratedElement instances will use the default behavior.
  MigratedElement.prototype._overrideLegacyUndefined = true;
  customElements.define('migrated-element', SomeElement);

Should I use it? This setting should only be used for migrating legacy codebases that depend on this behavior and is otherwise not recommended.

  • legacyWarnings / setLegacyWarnings

What does it do? This setting causes Polymer to warn if a component's template contains bindings to properties that are not listed in that element's properties block. For example:

  import {PolymerElement, html} from '@polymer/polymer/polymer-element.js';
  class SomeElement extends PolymerElement {
    static get template() {
      return html`<span>[[someProperty]] is used here</span>`;
    static get properties() {
      return { /* but `someProperty` is not declared here */ };
  customElements.define('some-element', SomeElement);

Only properties explicitly declared in the properties block are associated with an attribute and update when that attribute changes. Enabling this setting will show you where you might have forgotten to declare properties.

Should I use it? Consider using this feature during development but don't enable it in production.

  • orderedComputed / setOrderedComputed

What does it do? This setting causes Polymer to topologically sort each component's computed properties graph when the class is initialized and uses that order whenever computed properties are run.

For example:

  import {PolymerElement, html} from '@polymer/polymer/polymer-element.js';
  class SomeElement extends PolymerElement {
    static get properties() {
      return {
        a: {type: Number, value: 0},
        b: {type: Number, computed: 'computeB(a)'},
        c: {type: Number, computed: 'computeC(a, b)'},
    computeB(a) {
      console.log('Computing b...');
      return a + 1;
    computeC(a, b) {
      console.log('Computing c...');
      return (a + b) * 2;
  customElements.define('some-element', SomeElement);

When a changes, Polymer's default behavior does not specify the order in which its dependents will run. Given that both b and c depend directly on a, one of two possible orders could occur: [computeB, computeC] or [computeC, computeB].

  • In the first case - [computeB, computeC] - computeB is run with the new value of a and produces a new value for b. Then, computeC is run with both the new values of a and b to produce c.

  • In the second case - [computeC, computeB] - computeC is run first with the new value of a and the current value of b to produce c. Then, computeB is run with the new value of a to produce b. If computeB changed the value of b then computeC will be run again, with the new values of both a and b to produce the final value of c.

However, with orderedComputed enabled, the computed properties would have been previously sorted into [computeB, computeC], so updating a would cause them to run specifically in that order.

If your component's computed property graph contains cycles, the order in which they are run when using orderedComputed is still undefined.

Should I use it? The value of this setting depends on how your computed property functions are implemented. If they are pure and relatively inexpensive, you shouldn't need to enable this feature. If they have side effects that would make the order in which they are run important or are expensive enough that it would be a problem to run them multiple times for a property update, consider enabling it.

  • fastDomIf / setFastDomIf

What does it do? This setting enables a different implementation of <dom-if> that uses its host element's template stamping facilities (provided as part of PolymerElement) rather than including its own. This setting can help with performance but comes with a few caveats:

  • First, fastDomIf requires that every <dom-if> is in the shadow root of a Polymer element: you can't use a <dom-if> directly in the main document or inside a shadow root of an element that doesn't extend PolymerElement.

  • Second, because the fastDomIf implementation of <dom-if> doesn't include its own template stamping features, it doesn't create its own scope for property effects. This means that any properties you were previously setting on the <dom-if> will no longer be applied within its template, only properties of the host element are available.

Should I use it? This setting is recommended as long as your app doesn't use <dom-if> as described in the section above.

  • removeNestedTemplates / setRemoveNestedTemplates

What does it do? This setting causes Polymer to remove the child <template> elements used by <dom-if> and <dom-repeat> from the their containing templates. This can improve the performance of cloning your component's template when new instances are created.

Should I use it? This setting is generally recommended.

  • suppressTemplateNotifications / setSuppressTemplateNotifications

What does it do? This setting causes <dom-if> and <dom-repeat> not to dispatch dom-change events when their rendered content is updated. If you're using lots of <dom-if> and <dom-repeat> but not listening for these events, this setting lets you disable them and their associated dispatch work.

You can override the global setting for an individual <dom-if> or <dom-repeat> by setting its notify-dom-change boolean attribute:

  import {PolymerElement, html} from '@polymer/polymer/polymer-element.js';
  class SomeElement extends PolymerElement {
    static get properties() {
      return {
        visible: {type: Boolean, value: false},
    static get template() {
      return html`
        <button on-click="_toggle">Toggle</button>
        <!-- Set notify-dom-change to enable dom-change events for this particular <dom-if>. -->
        <dom-if if="[[visible]]" notify-dom-change on-dom-change="_onDomChange">
    _toggle() {
      this.visible = !this.visible;
    _onDomChange(e) {
      console.log("Received 'dom-change' event.");
  customElements.define('some-element', SomeElement);

Should I use it? This setting is generally recommended.

  • legacyNoObservedAttributes / setLegacyNoObservedAttributes

What does it do? This setting causes LegacyElementMixin not to use the browser's built-in mechanism for informing elements of attribute changes (i.e. observedAttributes and attributeChangedCallback), which lets Polymer skip computing the list of attributes it tells the browser to observe. Instead, LegacyElementMixin simulates this behavior by overriding attribute APIs on the element and calling attributeChangedCallback itself.

This setting has similar API restrictions to those of the custom elements polyfill. You should only use the element's setAttribute and removeAttribute methods to modify attributes: using (e.g.) the element's attributes property to modify its attributes is not supported with legacyNoObservedAttributes and won't properly trigger attributeChangedCallback or any property effects.

Components can override the global setting by setting their _legacyForceObservedAttributes property to true. This property's effects occur at startup; it won't have any effect if modified at runtime and should be set in the class definition.

Should I use it? This setting should only be used if startup time is significantly affected by Polymer's class initialization work - for example, if you have a large number of components being loaded but are only instantiating a small subset of them. Otherwise, this setting is not recommended.

  • useAdoptedStyleSheetsWithBuiltCSS / setUseAdoptedStyleSheetsWithBuiltCSS

What does it do? If your application is uses pre-built Shady CSS styles and your browser supports constructable stylesheet objects, this setting will cause Polymer to extract all <style> elements from your components' templates, join them into a single stylesheet, and share this stylesheet with all instances of the component using their shadow roots' adoptedStyleSheets array. This setting may improve your components' memory usage and performance depending on how many instances you create and how large their style sheets are.

Should I use it? Consider using this setting if your app already uses pre-built Shady CSS styles. Note that position-dependent CSS selectors (e.g. containing :nth-child()) may become unreliable for siblings of your components' styles as a result of runtime-detected browser support determining if styles are removed from your components' shadow roots.

Other new features


  • reuseChunkedInstances

What does it do? This boolean property causes <dom-repeat> to reuse template instances even when items is replaced with a new array, matching the Polymer 1 behavior.

By default, a <dom-repeat> with chunking enabled (i.e. initialCount >= 0) will drop all previously rendered template instances and create new ones whenever the items array is replaced. With reuseChunkedInstances set, any previously rendered template instances will instead be repopulated with data from the new array before new instances are created.

Should I use it? This flag is generally recommended and can improve rendering performance of chunked <dom-repeat> instances with live data.


  • disable-upgrade

What does it do? LegacyElementMixin now has built-in support for the disable-upgrade attribute (usually provided by DisableUpgradeMixin) that becomes active when the global legacyOptimizations setting is enabled, matching the Polymer 1 behavior.

Should I use it? Consider using this setting if you are already using the legacyOptimizations setting and migrating older components that depend on disable-upgrade without explicit application of DisableUpgradeMixin.

Bug fixes


  • Chunking behavior

<dom-repeat> no longer resets the number of rendered instances to initialCount when modifying items with PolymerElement's array modification methods (splice, push, etc.). The number of rendered instances will only be reset to initialCount if the items array itself is replaced with a new array object.

See #5631 for more information.

All commits

  • [ci skip] bump to 3.4.0 (commit)

  • shareBuiltCSSWithAdoptedStyleSheets -> useAdoptedStyleSheetsWithBuiltCSS (commit)

  • formatting (commit)

  • Fix incorrect JSDoc param name. (commit)

  • Gate feature behind shareBuiltCSSWithAdoptedStyleSheets; update tests. (commit)

  • Add shareBuiltCSSWithAdoptedStyleSheets global setting (commit)

  • Add stalebot config (commit)

  • Annotate more return types as !defined (#5642) (commit)

  • Ensure any previously enqueued rAF is canceled when re-rendering. Also, use instances length instead of renderedItemCount since it will be undefined on first render. (commit)

  • Improve comment. (commit)

  • Remove obsolete tests. (commit)

  • Simplify by making limit a derived value from existing state. This centralizes the calculation of limit based on changes to other state variables. (commit)

  • Update Sauce config to drop Safari 9, add 12 & 13. Safari 9 is now very old, and has micro task ordering bugs issues that make testing flaky. (commit)

  • Remove accidental commit of test.only (commit)

  • When re-enabling, ensure limit is at a good starting point and add a test for that. Also: * Ensure `itemsArrayChangedis cleared after every render. * Enqueue__continueChunkingAfterRaf` before notifying renderedItemCount for safety (commit)

  • Remove accidental commit of suite.only (commit)

  • Ensure limit is reset when initialCount is disabled. Note that any falsey value for initialCount (including 0) is interpreted as chunking disabled. This is consistent with 1.x logic, and follows from the logic of starting chunking by rendering zero items doesn't really make sense. (commit)

  • Updates from review. * Refactoring __render for readability * Removing __pool; this was never used in v2: since we reset the pool every update and items are only ever pushed at detach time and we only detach at the end of updates (as opposed to v1 which had more sophisticated splicing) (commit)

  • Store syncInfo on the dom-if, but null it in teardown. (same as invalidProps for non-fastDomIf) (commit)

  • Fixes for several related dom-repeat chunking issues. Fixes #5631. * Only restart chunking (resetting the list to the initialCount) if the items array itself changed (and not splices to the array), to match Polymer 1 behavior. * Add reuseChunkedInstances option to allow reusing instances even when items changes; this is likely the more common optimal case when using immutable data, but making it optional for backward compatibility. * Only measure render time and throttle the chunk size if we rendered a full chunk of new items. Ensures that fast re-renders of existing items don't cause the chunk size to scale up dramatically, subsequently causing too many new items to be created in one chunk. * Increase the limit by the chunk size as part of any render if there are new items to render, rather than only as a result of rendering. * Continue chunking by comparing the filtered item count to the limit (not the unfiltered item count). (commit)

  • Update comment. (commit)

  • Store syncInfo on instance and don't sync paths. Fixes #5629 (commit)

  • Avoid Array.find (doesn't exist in IE) (commit)

  • Add comment to skip. (commit)

  • Skip test when custom elements polyfill is in use (commit)

  • Copy flag to a single location rather than two. (commit)

  • Lint fix. (commit)

  • Update test name. (commit)

  • Introduce opt-out per class for legacyNoObservedAttributes (commit)

  • Ensure telemetry system works with legacyNoObservedAttributes setting (commit)

  • Update package-lock.json (commit)

  • Update test/unit/inheritance.html (commit)

  • Fix testing issues with latest webcomponentsjs (commit)

  • Allow undefined in legacy _template field to fall-through to normal lookup path. (commit)

  • re-add npm cache (commit)

  • regen package-lock (commit)

  • mispelled services, node 10 for consistency (commit)

  • modernize travis (commit)

  • Adds support for imperatively created elements to legacyNoObservedAttributes (commit)

  • Rebase sanitize dom value getter onto legacy-undefined-noBatch (#5618) (commit)

  • Add getSanitizeDOMValue to settings API (#5617) (commit)

  • FIx closure annotation (commit)

  • Fix closure annotation. (commit)

  • legacyNoObservedAttributes: Ensure user created runs before attributesChanged (commit)

  • Enable tests for legacyNoObservedAttributes (commit)

  • Only auto-use disable-upgrade if legacyOptimizations is set. (commit)

  • Adds disable-upgrade functionality directly to LegacyElementMixin (commit)

  • Add doc comment (commit)

  • Lint fixes. (commit)

  • Update externs. (commit)

  • Update extern format. (commit)

  • Address review feedback. (commit)

  • Address review feedback (commit)

  • Lint fixes. (commit)

  • Adds legacyNoAttributes setting (commit)

  • [ci skip] update changelog (commit)

  • Update polymer externs for new settings. (commit)

  • Update lib/utils/settings.js (commit)

  • Changes based on review. (commit)

  • Add basic support for adoptedStyleSheets (commit)

  • [ci skip] Add/fix comments per review. (commit)

  • Add missing externs for global settings. (commit)

  • Revert optimization to not wrap change notifications. This was causing a number of rendering tests to fail. Needs investigation, but possibly because wrapping calls ShadyDOM.flush, and this alters distribution timing which some tests may have inadvertently relied on. (commit)

  • Reintroduce suppressTemplateNotifications and gate Dom-change & renderedItemCount on that. Matches Polymer 1 setting for better backward compatibility. (commit)

  • Add notifyDomChange back to dom-if & dom-repeat to match P1. (commit)

  • Simplify host stack, set __dataHost unconditionally, and make _registerHost patchable. (commit)

  • Move @private annotation to decorate class definition. (commit)

  • Add type for _overrideLegacyUndefined. (commit)

  • Attempt to fix travis issues (commit)

  • Revert isAttached change based on review feedback. Deemed a breaking change. (commit)

  • Update travis to use xenial distro and, latest Firefox, and node 10 (commit)

  • Applies micro-optimizations and removes obsolete settings (commit)

  • Work around Closure Compiler bug to avoid upcoming type error (commit)

  • Only import each file once (#5588) (commit)

  • Avoid Array.from on Set. (commit)

  • Update nested template names. (commit)

  • Add runtime stamping tests around linking & unlinking effects. (commit)

  • Ensure parent is linked to child templateInfo. Fixes fastDomIf unstopping issue. (commit)

  • Remove unused TemplateInfo properties from types. (commit)

  • Add other used TemplateInfo property types. (commit)

  • Add type for TemplateInfo#parent. (commit)

  • [ci-skip] Add comment explaining confusing check in _addPropertyToAttributeMap (commit)

  • Ensure clients are flushed when runtime stamping via _stampTemplate. Maintains flush semantics with Templatizer stamping (relevant to fastDomIf, which is a switch between Templatizer-based stamping and runtime _stampTemplate-based stamping). Works around an issue with noPatch where nested undistributed dom-if's won't stamp. The changes to the tests are to remove testing that the full host tree is correct since the host doing the runtime stamping will no longer be the DOM getRootNode().host at ready time (this is exactly the case with Templatizer, whose semantics we intend to match). (commit)

  • Fix template-finding issue with DisableUpgrade mixin. The existing rules are that prototype._template is first priority and dom-module via is is second priority for a given class. A subclass has a new shot at overriding the previous template either by defining a new prototype._template or a new is resulting in a dom-module lookup. However, trivially subclassing a Polymer legacy element breaks these rules, since if there is no own prototype._template on the current class, it will lookup a dom-module using is from up the entire prototype chain. This defeats the rule that a prototype._template on the superclass should have taken priority over its dom-module. This change ensures that we only lookup dom-module if the class has an own is property. (commit)

  • Fix issue with camel cased properties and disable-upgrade (commit)

  • More closure fixes. (commit)

  • closure fixes (commit)

  • lint fixes (commit)

  • Fix issue with defaults overriding bound values when disable-upgrade is used. (commit)

  • Add closure types (commit)

  • Use DisbleUpgradeMixin in legacy class generation (commit)

  • Add comment about why code is duplicated. (commit)

  • Add tests for connected/disconnected while disabled (commit)

  • Improve comments. (commit)

  • Added comments. (commit)

  • Fix typo and improve readbility (commit)

  • Enable disable-upgrade when legacyOptimizations is set to true (commit)

  • Remove use of Object.create on template info (significant perf impact). (commit)

  • Attempt to sync host properties on every call to _showHideChildren. Fixes an issue where a dom-if that is toggled synchronously true-false-true could fail to sync properties invalidated while false, since the hidden state is only checked at render timing, and the newly added dirty-check could fail if the hidden state has been changed back to its initial value. (commit)

  • Add tests for extension and dom-if/repeat (commit)

  • Update stand alone disable-upgrade mixin. (commit)

  • Remove cruft from test (commit)

  • Simplify logic for disable-upgrade (commit)

  • Use a safer flag, based on internal testing. (commit)

  • Reorder based on review feedback. (commit)

  • Fix closure type. (commit)

  • Updated comment. (commit)

  • Ensure hasPaths is also accumulated as part of info necessary to sync. (commit)

  • Fix one more closure annotation. (commit)

  • Simplify algorithm; we already have list of computed deps in effect list. (commit)

  • Build computed graph from dependencies, rather than properties. (commit)

  • Fix closure annotations for dom-if. (commit)

  • Avoid lint warnings. (commit)

  • Minor simplifications/comments. (commit)

  • Updates from review. (commit)

  • Closure type fixes. (commit)

  • Initialize all settings from Polymer object when available. (commit)

  • Fix host prop merging. (commit)

  • Updates based on review. (commit)

  • Fix defaults back to false for new settings. (commit)

  • Add a dirty check to showHideChildren (commit)

  • Fix host property syncing (commit)

  • Adds disable-upgrade directly into legacy Polymer elements (commit)

  • Refactor DomIf into separate subclasses. (commit)

  • Runtime stamped dom-if (commit)

  • dom-if/dom-repeat bind-to-parent (commit)

  • Fix a few closure compiler issues (commit)

  • [ci skip] Add comment (commit)

  • Fix typo in comment (commit)

  • Cleanup, add tests. * remove old implementation * add API docs * rename some API * add dynamicFn to dep count * add test for method as dependency (commit)

  • [wip] Add additional topo-sort based algorithm. (commit)

  • Dedupe against a single turn on only under orderedComputed (commit)

  • Fix closure issues (commit)

  • Add hasPaths optimziation (commit)

  • Minor comment updates (commit)

  • Evaluate computed property dependencies first. Fixes #5143 (commit)

  • Add more externs (commit)

  • Fix lint warnings (commit)

  • Add comments per review feedback (commit)

  • Add legacyNotifyOrder. Improve comments. (commit)

  • Add test for literal-only static function. (commit)

  • Remove unnecessary literal check (commit)

  • Simplify (commit)

  • Add templatizer warnings. Move to legacyWarnings flag. (commit)

  • Add legacyUndefined and legacyNoBatch to externs (commit)

  • NOOP has to be an array for closure compiler (commit)

  • Add comments on warning limitations. (commit)

  • Ensure properties are set one-by-one at startup. (commit)

  • Remove unnecessary qualification. (commit)

  • Avoid over-warning on templatizer props and static dynamicFns. (commit)

  • Store splices directly on array when legacyUndefined is set (commit)

  • Fix test (commit)

  • Add arg length check (commit)

  • Adds legacyNoBatch setting (commit)

  • Add tests for legacyUndefined setting (commit)

  • Adds legacyUndefined setting (commit)

  • [ci skip] bump to 3.3.1 11f1f139
  • Merge pull request #5594 from rslawik/patch-1 e477a6f3
  • Merge pull request #5600 from Polymer/TimvdLippe-patch-2 dc20feca
  • Remove TimvdLippe from CODEOWNERS b99c2997
  • Merge pull request #5598 from Polymer/polymer-dom-api 8c69fb87
  • Add node field to PolymerDomApi 15747c83
  • Improve types for the template field on Polymer elements. (#5596) 4274bcec
  • Add module field 9a4d4d9a
  • Merge pull request #5584 from Polymer/closure-__hasRegisterFinished f6ccc9d1
  • Wrap other hasOwnProperty checks in JSCompiler_renameProperty. 0541b21a
  • Wrap hasOwnProperty checks for __hasRegisterFinished in JSCompiler_renameProperty(). 9e90fd2e
  • Merge pull request #5578 from Polymer/fix-placeholder-typing 96c125ee
  • Fix typing error in fixPlaceholder f050ce9e
  • Merge pull request #5577 from Polymer/ie-placeholder-binding 7d6d7152
  • Fix up comments based on feedback ab49f51a
  • Workaround bindings to textarea.placeholder in IE 61767da2
  • Add additional externs (#5575) 69ee4688
  • Merge pull request #5566 from Polymer/compile e7e4c241
  • Make Closure compiler happier about ShadyDOM access 46ee2aec
  • Remove other double import (#5565) 0d2c2e5d
  • Only use CONST_CASE for constants. (#5564) 54f8b47f
  • [skip ci] update changelog ac12b3bc


Other projects in HTML
Powered by Autocode - Instant Webhooks, Scripts and APIs
Autocode logo wordmark