🛠 Status: In Development

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.

LitElement uses lit-html to render into the element's Shadow DOM and adds API to help manage element properties and attributes. LitElement reacts to changes in properties and renders declaratively using lit-html. See the lit-html guide for additional information on how to create templates for lit-element.

• Setup properties: LitElement supports observable properties that cause the element to update. These properties can be declared in a few ways:

  • As class fields with the @property() decorator, if you're using a compiler that supports them, like TypeScript or Babel.
  • 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.

• React to changes: LitElement reacts to changes in properties and attributes by asynchronously rendering, ensuring changes are batched. This reduces overhead and maintains consistent state.

• Declarative rendering LitElement uses lit-html to declaratively describe how an element should render. Then lit-html ensures that updates are fast by creating the static DOM once and smartly updating only the parts of the DOM that change. Pass a JavaScript string to the html tag function, describing dynamic parts with standard JavaScript template expressions:

  • 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>`