lit.md

Lit Cheatsheet

• Reactive Properties
• Expressions
• Events
• Lifecycle

Reactive Properties

Lit's reactive properties system allows you to define properties on your custom element that automatically update the element when their values change.

Property Types

• String: a string value
• Number: a numeric value
• Boolean: a boolean value
• Array: an array value
• Object: an object value

Property Options

• attribute: the name of the HTML attribute to bind the property to
• reflect: whether or not to reflect the property value to the attribute
• converter: a function to convert the attribute value to the property value
• hasChanged: a function that determines if the property has changed
• type: the data type of the property
• state: Set to true to declare the property as internal reactive state. Internal reactive state triggers updates like public reactive properties, but Lit doesn't generate an attribute for it, and users shouldn't access it from outside the component. Equivalent to using the @state decorator.
• noAccessor: set to true to avoid generating the default property accessors.

Expressions

Expressions allow you to insert dynamic content into your template. You can use expressions by wrapping JavaScript code in ${}:

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

class MyElement extends LitElement {
  @property({ type: String }) name = '';

  render() {
    return html`<p>Hello, ${this.name}!</p>`;
  }
}

You can use expressions to bind values to form elements, such as inputs and selects. To bind a value to an input, you can use the .value property:

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

class MyElement extends LitElement {
  @property({ type: String }) name = '';

  render() {
    return html`
      <label for="name-input">Name:</label>
      <input id="name-input" .value=${this.name} @input=${this.handleInput} />
    `;
  }

  handleInput(event: Event) {
    this.name = (event.target as HTMLInputElement).value;
  }
}

In some cases, you may want to use the ? prefix on the property name instead of the .value syntax. This is useful when you want to bind to a boolean value.

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

class MyElement extends LitElement {
  @property({ type: Boolean }) checked = false;

  render() {
    return html`
      <input type="checkbox" ?checked=${this.checked} @change=${this.handleChange} />
    `;
  }

  handleChange(event: Event) {
    this.checked = (event.target as HTMLInputElement).checked;
  }
}

Events

To handle events, you can use the @event decorator to define a custom event:

import { LitElement, html } from 'lit';

class MyElement extends LitElement {
  @event({ type: 'my-event' }) myEvent;
  
  handleClick() {
    this.dispatchEvent(new CustomEvent('my-event', { detail: { message: 'Hello!' } }));
  }
  
  render() {
    return html`
      <button @click=${this.handleClick}>Click me</button>
    `;
  }
}

Lifecycle

Lit components use the standard custom element lifecycle methods. In addition Lit introduces a reactive update cycle that renders changes to DOM when reactive properties change.

• constructor(): Called when an element is created.
• connectedCallback(): Called when the element is added to the DOM.
• disconnectedCallback(): Called when the element is removed from the DOM.
• attributeChangedCallback(name, oldVal, newVal): Called when an observed attribute's value changes.
• adoptedCallback(): Invoked when a component is moved to a new document.

Reactive update cycle

• shouldUpdate(changedProps): Called before rendering to determine if the element should update. changedProps is an object containing the names and values of the properties that have changed since the last render.
• willUpdate(changedProps): Called before update() to compute values needed during the update.
• update(changedProps): Called to update the element's render tree. changedProps is an object containing the names and values of the properties that have changed since the last render.
• render(): Called to render the element's template. Should return a TemplateResult object.

Completing an update

After update() is called to render changes to the component's DOM, you can perform actions on the component's DOM using these methods.

• firstUpdated(changedProps): Called after the component's DOM has been updated the first time.
• updated(changedProps): Called whenever the component’s update finishes and the element's DOM has been updated and rendered.

For more information, see the Lit documentation.