Polymer Logo Home Guides Feature overview Try Polymer Tutorial: Build an element 1. Get set up 2. Add local DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties Define elements Register an element Declare properties Instance methods Behaviors Local DOM & styling Local DOM Styling Events Handle and fire events Gesture events Data system Data system concepts Work with object and array data Observers and computed properties Data binding Helper elements Tools Tools overview Polymer CLI Document your elements Test your elements Optimize for production Publish an element Advanced tools Services What's new Release notes 1.0 Migration guide About Polymer 1.0 Build apps Overview App templates Responsive app layout Routing Localization App storage Service worker Serve your app Resources Global settings Browser compatibility API API Reference Polymer.Base array-selector custom-style dom-bind dom-if dom-repeat dom-template Polymer.Templatizer

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.

Document-level global Polymer settings can be set by creating a Polymer object on window before importing the Polymer library:

<html> <head> <meta charset="utf-8"> <script src="components/webcomponentsjs/webcomponents-lite.js"></script> <script> /* this script must run before Polymer is imported */ window.Polymer = { dom: 'shadow', lazyRegister: true }; </script> <!-- import a component that relies on Polymer --> <link rel="import" href="elements/my-app.html"> </head> <body> ...

Settings can also be switched on the URL query string:

http://example.com/test-app/index.html?dom=shadow

Available settings are listed below.

Setting Description
disableUpgradeEnabled When true, allows elements to be selectively marked for deferred upgrade. This is a lightweight feature useful for performance tuning an application, giving fine-grained control over individual element instantiation cost.

When an element is marked with the disable-upgrade attribute, its createdCallback returns early without performing any of the normal Polymer element initialization steps (for example, stamping the template, setting default properties, running observers, and so on). The element behaves like an element that has not had its definition loaded, except that it has the correct prototype (as such, methods should not be called on the element until its disable-upgrade attribute has been removed).

Removing the disable-upgrade attribute causes the element to boot up, initialize its properties, stamp its template, and so on.

Note this feature is implemented as an attribute API only. There is no corresponding disableUpgrade property. As such, any bindings should be via attribute bindings. For example:

<my-element disable-upgrade$="{{!loggedIn}}"></my-element>
dom Controls how local DOM is rendered. Options:
  • "shady". All local DOM is rendered using shady DOM, even where shadow DOM is supported (current default).
  • "shadow". Local DOM is rendered using shadow DOM where supported (this will be the default in the future).
lazyRegister Improves startup time by allowing some some registration time activities to be deferred. Options:
  • true. Many registration-time activities are deferred until the first instance of an element type is created. Defaults to false. (This default may change in the future.)
  • "max". Defers all behavior work until first element creation. When setting lazyRegister to "max", you cannot set an element's is property or create a custom constructor by defining the factoryImpl method. Polymer calls your element's beforeRegister to preserve the ability to define elements using ES6. The element's beforeRegister is called before the behavior's.
noUrlSettings When true, Polymer settings can only be sent from a script in the page. In other words, URL query parameters such as `?dom=shadow` will be ignored. Defaults to false.
passiveTouchGestures

When true, Polymer gestures event listeners are all added as passive listeners, and can't call preventDefault to prevent the native browser handling. May improve scroll performance. Defaults to false.

See Gesture events for more information.

suppressBindingNotifications When true, disables notify effects when propagating data downward through bindings. Generally these are not useful unless you are explicitly adding a binding and a property change notification event listener on the same element: 
 <my-el foo="{{foo}} on-foo-changed="handleFoo"></my-el>

With this binding, when the host changes the value of foo, its handleFoo method is invoked to handle the change notification event. This pattern is generally unnecessary since the host element doing the binding can use a foo observer instead.

With suppressBindingNotifications: true, the event isn't fired when the host changes the value (but is still fired if `my-el` changes its foo value internally.)

If your code doesn't don't use this pattern, enabling this flag should improve data system performance.
suppressTemplateNotifications When true, suppresses dom-change and rendered-item-count events from dom-if, dom-repeat, and dom-bind elements. Users can opt back into dom-change events by setting the notify-dom-change attribute (notifyDomChange: true property) on individual dom-if and dom-repeat instances.
useNativeCSSProperties When true, Polymer uses native custom CSS properties if the browser supports them. Defaults to false because of Safari 9 support being buggy. See the 1.6.0 release notes for more information.