Home Start Get started Quick tour of Polymer Install Polymer 2.x 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 About this release What's new in 2.0 Upgrade guide Hybrid elements Release notes Custom elements Custom element concepts Define an element Declare properties Shadow DOM & styling Shadow DOM concepts DOM templating Style shadow DOM Custom CSS properties 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 Browser support Overview Polyfills ES6 Tools Tools overview Polymer CLI CLI commands Create an element project Create an application project Document your elements Test your elements Web services polymer.json specification Node support Resources Glossary API Reference API Reference Global settings App Toolbox What's in the box? Using the Toolbox App templates Responsive app layout Routing Localization App storage Service worker Deploy Build for production Serve your app The PRPL pattern Case study Shop News Blog Community Feature overview
About this release
What's new in 2.0 Upgrade guide Hybrid elements Release notes
Custom elements
Custom element concepts Define an element Declare properties
Shadow DOM & styling
Shadow DOM concepts DOM templating Style shadow DOM Custom CSS properties
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
Browser support
Overview Polyfills ES6
Tools
Tools overview Polymer CLI CLI commands Create an element project Create an application project Document your elements Test your elements Web services polymer.json specification Node support
Resources
Glossary
API Reference
API Reference 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.
  • 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="x-custom">
      <!-- Optional shadow DOM template -->
      <template>
        <style>
          /* CSS rules for your element */
        </style>

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

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

      <script>
        // Define the element's API using an ES2015 class
        class XCustom extends Polymer.Element {

          static get is() { return 'x-custom'; }

          // Declare properties for the element's public API
          static get properties() {
            return {
              greeting: {
                type: String,
                value: "Hello!"
              }
            }
          }

          // Add methods to the element's public API
          greetMe() {
            console.log(this.greeting);
          }

        }

        // Register the x-custom element with the browser
        customElements.define(XCustom.is, XCustom);
      </script>

    </dom-module>

This guide divides the features into the following groups:

  • Custom elements. Registering an element associates a class with a custom element name. The element provides callbacks to manage its lifecycle. Polymer also lets you declare properties, to integrate your element's property API with the Polymer data system.

  • Shadow DOM. Shadow DOM provides a local, encapsulated DOM tree for your element. Polymer can automatically create and populate a shadow tree for your element from a DOM template.

  • Events. Polymer provides a declarative syntax for attaching event listeners to shadow DOM children. It also provides an optional library for handling gesture events.

  • Data system. The Polymer data system provides data binding to properties and attributes; property observers; and computed properties.

If you're upgrading an existing 1.x element to the new APIs, see the Upgrade guide for advice.

If you're looking for the latest changes in this release, see the Release notes.