@polymer/lit-element

🛠 Status: Moved to lit-element

LitElement is currently in development. It's on the fast track to a 1.0 release, so we encourage you to use it and give us your feedback, but there are things that haven't been finalized yet and you can expect some changes.

A simple base class for creating fast, lightweight web components

* As class fields with the `@property()` [decorator](https://github.com/tc39/proposal-decorators#decorators),
if you're using a compiler that supports them, like [TypeScript](https://www.typescriptlang.org/) or [Babel](https://babeljs.io/docs/en/babel-plugin-proposal-decorators).
* With a static `properties` getter.
* By manually writing getters and setters. This can be useful if tasks should
be performed when a property is set, for example validation. Call `requestUpdate(name, oldValue)`
in the setter to trigger an update and use any configured property options.

Properties can be given an `options` argument which is an object that describes how to
process the property. This can be done either in the `@property({...})` decorator or in the
object returned from the `properties` getter, e.g. `static get properties { return { foo: {...} }`.

Property options include:

* `attribute`: Indicates how and whether the property becomes an observed attribute.
If the value is `false`, the property is not added to the static `observedAttributes` getter.
If `true` or absent, the lowercased property name is observed (e.g. `fooBar` becomes `foobar`).
If a string, the string value is observed (e.g `attribute: 'foo-bar'`).
* `converter`: Indicates how to convert the attribute to/from a property.
The value can be a function used for both serialization and deserialization, or it can
be an object with individual functions via the optional keys, `fromAttribute` and `toAttribute`.
A default `converter` is used if none is provided; it supports
`Boolean`, `String`, `Number`, `Object`, and `Array`.
* `type`: Indicates the type of the property. This is used only as a hint for the
`converter` to determine how to convert the attribute
to/from a property. Note, when a property changes and the converter is used
to update the attribute, the property is never updated again as a result of
the attribute changing, and vice versa.
* `reflect`: Indicates whether the property should reflect to its associated
attribute (as determined by the attribute option). If `true`, when the
property is set, the attribute which name is determined according to the
rules for the `attribute` property option will be set to the value of the
property converted using the rules from the `type` and `converter`
property options.
* `hasChanged`: A function that indicates whether a property should be considered
changed when it is set and thus result in an update. The function should take the
`newValue` and `oldValue` and return `true` if an update should be requested.

* static elements: ``` html`<div>Hi</div>` ```
* expression: ``` html`<div>${this.disabled ? 'Off' : 'On'}</div>` ```
* property: ``` html`<x-foo .bar="${this.bar}"></x-foo>` ```
* attribute: ``` html`<div class="${this.color} special"></div>` ```
* boolean attribute: ``` html`<input type="checkbox" ?checked=${checked}>` ```
* event handler: ``` html`<button @click="${this._clickHandler}"></button>` ```

* Runs in all [supported](#supported-browsers) browsers: [Glitch](https://glitch.com/edit/#!/hello-lit-element?path=index.html)

* Runs in browsers with [JavaScript Modules](https://caniuse.com/#search=modules): [JSFiddle](https://jsfiddle.net/rzhofu81/), [JSBin](http://jsbin.com/vecuyan/edit?html,output),

1. Add LitElement to your project:

    ```npm i @polymer/lit-element```

1. Install the webcomponents polyfill. If you're developing a reusable package, this should be a dev dependency which you load in your tests, demos, etc.

    ```npm i -D @webcomponents/webcomponentsjs```


1. Create an element by extending LitElement and calling `customElements.define` with your class (see the examples below).

1. Install the Polymer CLI:

    ```npm i -g polymer-cli```

1. Run the development server and open a browser pointing to its URL:

    ```polymer serve```

> LitElement is published on [npm](https://www.npmjs.com/package/@polymer/lit-element) using JavaScript Modules.
This means it can take advantage of the standard native JavaScript module loader available in all current major browsers.
>
> However, since LitElement uses npm convention to reference dependencies by name, a light transform to rewrite specifiers to URLs is required to get it to run in the browser. The polymer-cli's development server `polymer serve` automatically handles this transform.

Tools like [WebPack](https://webpack.js.org/) and [Rollup](https://rollupjs.org/) can also be used to serve and/or bundle LitElement.

Minimal Example

<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
<script type="module">
  import {LitElement, html} from '@polymer/lit-element';

  class MyElement extends LitElement {

    static get properties() {
      return {
        mood: {type: String}
      };
    }

    constructor() {
      super();
      this.mood = 'happy';
    }

    render() {
      return html`<style> .mood { color: green; } </style>
        Web Components are <span class="mood">${this.mood}</span>!`;
    }

  }

  customElements.define('my-element', MyElement);
</script>

<my-element mood="happy"></my-element>

API Documentation

Advanced: Update Lifecycle

• A property is set (e.g. element.foo = 5).
• If the property's hasChanged(value, oldValue) returns false, the element does not

• requestUpdate(): Updates the element after awaiting a microtask (at the end

• performUpdate(): Performs the update, calling the rest of the update API.
• shouldUpdate(changedProperties): The update proceeds if this returns true, which

• update(changedProperties): Updates the element. Setting properties inside this

import {LitElement, html, property} from '@polymer/lit-element';

class MyElement extends LitElement {

  // Public property API that triggers re-render (synced with attributes)
  @property()
  foo = 'foo';

  @property({type: Number})
  whales = 5;

  constructor() {
    super();
    this.addEventListener('click', async (e) => {
      this.whales++;
      await this.updateComplete;
      this.dispatchEvent(new CustomEvent('whales', {detail: {whales: this.whales}}))
    });
  }

  // Render method should return a `TemplateResult` using the provided lit-html `html` tag function
  render() {
    return html`
      <style>
        :host {
          display: block;
        }
        :host([hidden]) {
          display: none;
        }
      </style>
      <h4>Foo: ${this.foo}</h4>
      <div>whales: ${'🐳'.repeat(this.whales)}</div>
      <slot></slot>
    `;
  }

}
customElements.define('my-element', MyElement);

<my-element whales="5">hi</my-element>

Supported Browsers

Known Issues

• On very old versions of Safari (<=9) or Chrome (<=41), properties created for native