Get started with web components and Lit

When building plugins, we recommend using lightweight frameworks that are designed to create web components and manipulate the ShadowDOM.

Frameworks such as React and Angular are designed to build full web applications, and can add a lot of code your plugin won't use, which will increase the load time of your forms. As JQuery does not support the ShadowDOM, you may find building plugins with JQuery difficult.

We've chosen Lit as a good example of a lightweight framework that will help you build plugins easily. You do not need to use Lit: any framework that supports web components and ShadowDOM can be used to create plugins.

You can use Lit with JavaScript or with compilers such as Babel or TypeScript. Using compilers allows you to make use of decorators to add reactive properties, declarative event listeners, and queries.

What is Lit?

Lit is a library for building lightweight web components.

To learn more about developing with Lit, see:

• Introduction to Lit (YouTube)
• Introduction to Lit (developer tutorials)
• Lit learning centre

The Lit documentation also provides additional tutorials and a development playground.

 

Define a web component in Lit

Lit defines web components as custom HTML elements:

• Components are defined as a class that extends LitElement.
• Components can have reactive properties, which automatically trigger a re-rendering of the component when they are changed, such as the message property in the example. Custom fields in your plugin's contract automatically connect with reactive properties of the same name. See Create a custom configuration field.
• Components can also have encapsulated styles, which control the component's appearance without impacting other elements, such as the highlight style in the example.
• Each component has a render() function that uses Templates to define how the web component renders on the page.

Note: The render() function is automatically called to update the component in the DOM when any reactive property is changed. For best practice, avoid manipulating the DOM outside of the render() function. See Rendering in the Lit documentation.

• TypeScript
• JavaScript

import {LitElement, html} from 'lit';
@customElement('my-plugin')
export class MyPlugin extends LitElement {
  @property()
  message = 'Hello World';

  static styles = css`
    .highlight {
      font-weight: 700;
      color: #E8960A;
    }
  `;

  render() {
    return html`
      </div id="pluginDiv">
        </p>This is a template.</p>
        </p>This is my message ${this.message}.</p>
      </div>
	`;
  }
}

import {LitElement, html} from 'lit';
export class MyPlugin extends LitElement {
  static properties = {
    message: {},
  };

  static styles = css`
    .highlight {
      font-weight: 700;
      color: #E8960A;
  }
`;

  constructor() {
    super();
    this.message = 'Hello World';
  }

  render() {
    return html`
      </div id="pluginDiv">
        <p>This is a template.</p>
        <p>This is my message ${this.message}.</p>
      </div>
	`;
  }
}
customElements.define('my-plugin', MyPlugin);

Compose with expressions and sub-templates

Templates can use expressions, such as the ${this.message} expression in the second <p> tag. The expression uses the message property of the component, and will be evaluated by Lit's html function.

Templates can also be composed of sub-templates, allowing you to decompose a larger template into reusable pieces. To use sub-templates:

1. Create functions that return parts of your template using Lit's html function.
2. In your render() method, use expressions to call the sub-template functions where required.

For more information, see Rendering in the Lit documentation.

Web components can be selected and assigned to a property using the @query() decorator in Typescript or the querySelector() function in JavaScript.

For more information on accessing nodes in the ShadowDOM with Lit, see the Lit documentation.

• TypeScript
• JavaScript

@query('#pluginDiv')
myPlugin!: HTMLElement;

get myPlugin() {
  return this.renderRoot?.querySelector('#pluginDiv') ?? null;
}

1. Create a custom event, specifying the event type and options.
   • Set the bubbles property to true to allow the event to propagate up the DOM tree.
   • Set the composed property to true to allow the event to propagate from the ShadowDOM to the standard DOM.
   • Add any additional information you want to send in the detail property.
2. Dispatch the event you created using dispatchEvent().