Home Start Get started Build an element 1. Get set up 2. Add local DOM 3. Data binding & properties 4. React to input 5. Theming with custom properties Build an app 1. Get set up 2. Create a new page 3. Add some elements 4. Deploy Polymer Feature overview Quick tour 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 Resources Community Browser compatibility API Reference Polymer.Base array-selector custom-style dom-bind dom-if dom-repeat dom-template Polymer.Templatizer Global settings App Toolbox What's in the box? Using the Toolbox App templates Responsive app layout Routing Localization App storage Service worker Serve your app Case study Shop News Blog Community Feature overview Quick tour
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
Resources
Community Browser compatibility
API Reference
Polymer.Base array-selector custom-style dom-bind dom-if dom-repeat dom-template Polymer.Templatizer Global settings

The Polymer library provides a set of features for creating custom elements. These features are designed to make it easier and faster to make custom elements that work like standard DOM elements. Similar to standard DOM elements, Polymer elements can be:

  • Instantiated using a constructor or document.createElement.
  • Configured using attributes or properties.
  • Populated with internal DOM inside each instance.
  • Responsive to property and attribute changes (for example, by populating data into the DOM, or firing an event).
  • Styled with internal defaults or externally.
  • Responsive to methods that manipulate its internal state.

A basic Polymer element definition looks like this:

    <dom-module id="element-name">

      <template>
        <style>
          /* CSS rules for your element */
        </style>

        <!-- local DOM for your element -->

        <div>{{greeting}}</div> <!-- data bindings in local DOM -->
      </template>

      <script>
        // element registration
        Polymer({
          is: "element-name",

          // add properties and methods on the element's prototype

          properties: {
            // declare properties for the element's public API
            greeting: {
              type: String,
              value: "Hello!"
            }
          }
        });
      </script>

    </dom-module>

This guide divides the features into the following groups:

  • Registration and lifecycle. Registering an element associates a class (prototype) with a custom element name. The element provides callbacks to manage its lifecycle. Use behaviors to share code.

  • Declared properties. Declared properties can be configured from markup using attributes. Declared properties can optionally support change observers, two-way data binding, and reflection to attributes. You can also declare computed properties and read-only properties.

  • Local DOM. Local DOM is the DOM created and managed by the element.

  • Events. Attaching event listeners to the host object and local DOM children. Event retargeting.

  • Data binding. Property bindings. Binding to attributes.

  • Behaviors. Behaviors are reusable modules of code that can be mixed into Polymer elements.

  • Utility functions. Helper methods for common tasks.

  • Experimental features and elements. Experimental template and styling features. Feature layering.

If you're migrating an existing 0.5 element to the new APIs, see the Migration guide for advice.

If you're upgrading from the 0.8 release, see the Release notes.