Document-level global Polymer settings can be set by creating a Polymer object on window before importing the Polymer library, or by calling a setter.

You should call the setters before defining your first Polymer element. For example, you could do this from an entrypoint file, or from your main application element import (assuming that you have an main application element that's always loaded first.)

Calling a setter from an entrypoint:

<html>
  <head>
  <meta charset="utf-8">
  <script src="components/webcomponentsjs/webcomponents-loader.js"></script>
  <!-- import just the settings module, or polymer-element.html or polymer.html -->
  <link rel="import" href="components/polymer/lib/util/settings.html">
  <script>
    Polymer.setPassiveTouchGestures(true);
  </script>
  <link rel="import" href="src/my-app.html">
  ...

Calling setter from the main application import:

<link rel="import" href="components/polymer/polymer-element.html">

<script>
  Polymer.setPassiveTouchGestures(true);

  class MyApp extends Polymer.Element {
    ...
</script>

Defining a Polymer object:

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

Available settings:

Setting / Setter Description
setPassiveTouchGestures

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.

This setting can't be set from the Polymer object—the application must use the setter before any gesture event listeners are added.

See Native browser gesture handling for more information on gesture events and native browsers gestures.

rootPath
setRootPath
Sets a global rootPath property that can be used in templates to generate URLs that are relative to the application root.
sanitizeDOMValue
setSanitizeDOMValue
A global callback used to sanitize any value before inserting it into the DOM. The callback signature is:
Polymer = {
  sanitizeDOMValue: function(value, name, type, node) { ... }
}

Where:

  • value is the value to sanitize.
  • name is the name of an attribute or property (for example, href).
  • type indicates where the value is being inserted: one of property, attribute, or text.
  • node is the node where the value is being inserted.

There are also a number of polyfill-specific settings. See Polyfills for details.