The Polymer library is in maintenance mode. For new development, we recommend Lit.

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.

Legacy elements use a different set of lifecycle callbacks than standard Polymer 3.x elements. These callbacks are based on the custom elements v0 lifecycle that was supported in Polymer 1.x.

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 its shadow DOM tree 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.)

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.