To define a custom element, create a class that extends Polymer.Element and pass the class to the customElements.define method.

By specification, the custom element's name must start with a lower-case ASCII letter and must contain a dash (-).


// define the element's class element
class MyElement extends Polymer.Element {

  // Element class can define custom element reactions
  connectedCallback() {
    console.log('my-element created!');

  ready() {
    this.textContent = 'I\'m a custom element!';

// Associate the new class with an element name
customElements.define('my-element', MyElement);

// create an instance with createElement:
var el1 = document.createElement('my-element');

// ... or with the constructor:
var el2 = new MyElement();

As shown above, the element's class can define callbacks for the custom element reactions as described in Custom element lifecycle.

You can leverage native subclassing support provided by ES6 to extend and customize existing elements defined using ES6 syntax:

// Subclass existing element
class MyElementSubclass extends MyElement {
  static get is() { return 'my-element-subclass'; }
  static get properties() { ... }
  constructor() {

// Register custom element definition using standard platform API
customElements.define(, MyElementSubclass);

For more information on extending elements, see Extending other elements in Custom element concepts.

If you don't provide a template for your subclass, it inherits the superclass's template by default. To override this behavior, or modify the superclass template, override the subclass's template getter.

You can share code using mixins. You use a mixin to add new features on top of a base class:

class MyElementWithMixin extends MyMixin(Polymer.Element) {


This pattern may be easier to understand if you think of it as two steps:

// Create a new base class that adds MyMixin's features to Polymer.Element
const BaseClassWithMixin = MyMixin(Polymer.Element);

// Extend the new base class
class MyElementWithMixin extends BaseClassWithMixin { ... }

Because mixins are simply adding classes to the inheritance chain, all of the usual rules of inheritance apply.

For information on defining mixins, see Sharing code with class expression mixins in Custom element concepts.

There are three main HTML imports for defining Polymer elements:

Import Description
polymer-element.html Defines the Polymer.Element base class.
legacy-element.html Defines the Polymer.LegacyElementMixin base class, which can be used to add 1.x compatible legacy API to Polymer.Element. Also defines the legacy Polymer() factory method for creating hybrid elements. (Includes polymer-element.html.)
polymer.html Includes the previous imports plus the helper elements (custom-style, dom-bind, dom-if, and dom-repeat) that were included in the 1.x polymer.html bundle.

For the smallest footprint, use the polymer-element.html import and import any required helper elements separately.

If you need some of the backwards-compabile APIs from 1.x, you can use the Polymer.LegacyElement class as the base for 2.x class-style elements. You must still import any helper elements you use individually.

Use the polymer.html import for defining hybrid elements that can run under both 1.x and 2.x.

You can add hybrid behaviors to your class-style element using the Polymer.mixinBehavior function:

class XClass extends Polymer.mixinBehaviors([MyBehavior, MyBehavior2], Polymer.Element) {

customElements.define('x-class', XClass);

The mixinBehavior function also mixes in the Legacy APIs, the same as if you extended Polymer.LegacyElement. These APIs are required since since hybrid behaviors depend on them.

You should only define elements from the main document when experimenting. In production, elements should always be defined in separate files and imported into your main document.

To define an element in your main HTML document, define the element from HTMLImports.whenReady(callback). callback is invoked when all imports in the document have finished loading.

<!DOCTYPE html>
    <script src="bower_components/webcomponentsjs/webcomponents-lite.js">
    <link rel="import" href="bower_components/polymer/polymer-element.html">
    <title>Defining a Polymer Element from the Main Document</title>
    <dom-module id="main-document-element">
          Hi! I'm a Polymer element that was defined in the
          main document!
        HTMLImports.whenReady(function() {
          class MainDocumentElement extends Polymer.Element {

            static get is() { return 'main-document-element'; }

          window.customElements.define(, MainDocumentElement);

Legacy elements can use use the Polymer function to register an element. The function takes as its argument the prototype for the new element. The prototype must have an is property that specifies the HTML tag name for your custom element.

By specification, the custom element's name must start with an ASCII letter and contain a dash (-).


    // register an element
    MyElement = Polymer({

      is: 'my-element',

      // See below for lifecycle callbacks
      created: function() {
        this.textContent = 'My element!';


    // create an instance with createElement:
    var el1 = document.createElement('my-element');

    // ... or with the constructor:
    var el2 = new MyElement();

The Polymer function registers the element with the browser and returns a constructor that can be used to create new instances of your element via code.

The Polymer function sets up the prototype chain for your custom element, chaining it to the Polymer Base prototype (which provides Polymer value-added features), so you cannot set up your own prototype chain. However, you can use behaviors to share code between elements.

The Polymer.Element class implements the standard Custom Element lifecycle callbacks to perform tasks necessary for Polymer's built-in features.

Polymer adds an extra callback, ready, which is invoked when Polymer has finished creating and initializing the element's DOM.

Legacy callback Description
created Called when the element has been created, but before property values are set and local DOM is initialized.

Use for one-time set-up before property values are set.

Equivalent to the native constructor.

ready Called after property values are set and local DOM is initialized.

Use for one-time configuration of your component after local DOM is initialized. (For configuration based on property values, it may be preferable to use an observer.)

attached Called after the element is attached to the document. Can be called multiple times during the lifetime of an element. The first attached callback is guaranteed not to fire until after ready.

Uses include adding document-level event listeners. (For listeners local to the element, you can use declarative event handling, such as annotated event listeners or the listeners object.)

Equivalent to native connectedCallback.

detached Called after the element is detached from the document. Can be called multiple times during the lifetime of an element.

Uses include removing event listeners added in attached.

Equivalent to native disconnectedCallback.

attributeChanged Called when one of the element's attributes is changed.

Use to handle attribute changes that don't correspond to declared properties. (For declared properties, Polymer handles attribute changes automatically as described in attribute deserialization.)

Equivalent to the native attributeChangedCallback.

Legacy elements can share code in the form of behaviors, which can define properties, lifecycle callbacks, event listeners, and other features.

For more information, see Behaviors in the Polymer 1.x docs.