Skip to main content

Defining a component

Define a Lit component by creating a class extending LitElement and registering your class with the browser:

The @customElement decorator is shorthand for calling customElements.define, which registers a custom element class with the browser and associates it with an element name (in this case, simple-greeting).

If you're using JavaScript, or if you're not using decorators, you can call define() directly:

A Lit component is an HTML element

Permalink to A Lit component is an HTML element

When you define a Lit component, you're defining a custom HTML element. So you can use the new element like you'd use any built-in element:

The LitElement base class is a subclass of HTMLElement, so a Lit component inherits all of the standard HTMLElement properties and methods.

Specifically, LitElement inherits from ReactiveElement, which implements reactive properties, and in turn inherits from HTMLElement.

Inheritance diagram showing LitElement inheriting from ReactiveElement, which in turn inherits from HTMLElement. LitElement is responsible for templating; ReactiveElement is responsible for managing reactive properties and attributes; HTMLElement is the standard DOM interface shared by all native HTML elements and custom elements.

TypeScript will infer the class of an HTML element returned from certain DOM APIs based on the tag name. For example, document.createElement('img') returns an HTMLImageElement instance with a src: string property.

Custom elements can get this same treatment by adding to the HTMLElementTagNameMap as follows:

By doing this, the following code properly type-checks:

We recommend adding an HTMLElementTagNameMap entry for all elements authored in TypeScript, and ensuring you publish your .d.ts typings in your npm package.