Feature Overview

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. With a standard DOM element, you might expect:

• You can create it using a constructor or document.createElement.
• You can configure it using attributes or properties.
• It may have some internal DOM that's created for each instance.
• It responds to property and attribute changes (for example, by populating data into the DOM, or firing an event).
• It has some default style and can be styled from the outside.
• It may provide methods to allow you to manipulate its internal state.

A basic Polymer element definition looks like this:

element_name.html:

<dom-module id="element-name">
  <style>
    /* CSS rules for your element */
  </style>
  <template>
    <!-- local DOM for your element -->
    <div>{{greeting}}</div> <!-- data bindings in local DOM -->
  </template>
</dom-module>

element_name.dart:

@HtmlImport('element_name.html')
library my_package.element_name;
    
import 'package:polymer/polymer.dart';
import 'package:web_components/web_components.dart' show HtmlImport;

@PolymerRegister('element-name')
class ElementName extends PolymerElement {
  ElementName.created() : super.created();
      
  @property
  String greeting = 'Hello!';
}

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.