The Lit Cheat Sheet

Feb 3, 2025 — Updated Feb 3, 2025

Do you need a quick reference for the basics of Lit? Look no further! This cheat sheet will help you get started with, or just remember, the features of Lit.

If you are coming from another framework, you might also want to supplement this article with Component Party which compares basic concepts across different frameworks. Just make sure that Lit is selected at the top of the page!

LitElement is the base class for all Lit components.

@customElementcustomElements.defineis where you associate the name of your component with the class definition / logic of that component.

render() is the method where you define your component's template using a tagged template literal with html.

Write your HTML in the html tagged template literal.

Related Documentation & Topics:

• Defining a Component
• LitElement
• @customElement
• customElements.define
• Rendering
• How to build your first Lit component (Video)
• How to style your Lit elements

To use a component, import the file with its definition.

Related Documentation & Topics:

• import (external)
• import() (external)
• JavaScript modules (external)
• @customElement
• customElements.define (external)
• Local dev servers (bare module specifiers)

Use the html tagged template literal to define your component's template.

Related Documentation & Topics:

• Templates Overview
• Rendering

Use standard JavaScript conditional expressions in your template to conditionally render content.

Related Documentation & Topics:

• Conditionals
• Expressions

Lit-html has three types of built-in expressions to set attributes or properties on elements:

• Property expressions .prop=${value}
• Attribute expressions attr=${value}
• Boolean attribute expressions ?attr=${value}

Related Documentation & Topics:

• Expressions
• Expressions – Attribute Expressions
• Expressions – Property Expressions

Lit-html has a built-in event listener expression to add event listeners to elements. You can also use event listeners to mimic two-way databinding with input elements.

Related Documentation & Topics:

• Expressions
• Expressions – Event listener expressions
• Events
• Event communication between web components (video)
• Customizing event listener options
• A complete guide on shadow DOM and event propagation (external)

Lit-html can render JavaScript arrays and iterables. For most simple use cases, you can use the Array.map() method to render arrays of items or the map() directive to render any other iterables. This pattern is best used for short, simple lists.

Related Documentation & Topics:

• Lists
• Working With Lists Tutorial
• Built-in directives – map()
• Built-in directives – range()
• Built-in directives – join()

For long lists that may change frequently, use the repeat() directive to efficiently re-render only the items that have changed.

• Lists
• Working With Lists Tutorial – The repeat() directive
• Built-in directives – repeat()

For lists that are so long that it would be impractical to render all items at once, use the Lit Virtualizer to render only the items that are currently in view.

Related Documentation & Topics:

• Lit Virtualizer Documentation (external)
• Lit Labs: Virtualizer (video)

To render a string of HTML as HTML in Lit, use the unsafeHTML directive.

Related Documentation & Topics:

• Built-in directives – unsafeHTML
• innerHTML Security considerations (external)

In rare cases, you need to bind to an HTML tag name to change the rendered element. You can do this safely with the static-html module and the literal template tag.

Related Documentation & Topics:

• Static Expressions

In even rarer cases, you need to bind any arbitrary string value to an HTML tag name to change the rendered element. You can do this with the unsafeStatic() directive. This may be helpful if you are implementing an SSR framework that uses lit-html for rendering.

• Non-literal Statics
• Static Expressions

Add styles by defining the static styles property. Write CSS in the css tagged template literal.

Related Documentation & Topics:

• Styles

Styles only apply to the current element. That means you can feel free to use super generic selectors that you'd normally have to make up class names for.

Related Documentation & Topics:

• Styles
• Shadow DOM

To conditionally apply styles it's generally best to use classMap.

Related Documentation & Topics:

• Defining Scoped Styles in the template
• classMap
• classMap tsdoc
• Playground example

You can share Lit stylesheets with other components by exporting them from a module and importing them into another.

• Styling
• Sharing Styles

CSS Custom Properties can pierce multiple shadow roots allowing you to share values for specific properties.

Related Documentation & Topics:

• CSS Custom Properties
• Theming
• How to style your Lit elements (Video)

CSS Shadow Parts are exposed by components with the part="<part-name>" attribute.

Shadow Parts can pierce individual shadow roots allowing you to set arbitrary styles on a given node using the ::part(<part-name>) pseudo-element.

Related Documentation & Topics:

• How to style your Lit elements (video)
• CSS Shadow Parts (external)
• ::part (external)

CSS Shadow part names can only apply to the targeted element. You need to use exportparts to expose a shadow part in nested shadow roots.

You can export multiple parts by separating them with a comma (,).

You can also rename parts with a colon (:).

Related Documentation & Topics:

• exportparts (external)
• How to style your Lit elements (video)
• CSS Shadow Parts (external)
• ::part (external)

In some rare cases, you may receive trusted styles as a string and may need to apply them to a component. You can do this with native, constructable stylesheets.

Related Documentation & Topics:

• Constructable Stylesheets (external)
• CSSResultOrNative

In some cases, you may want to import styles in the form of a CSS files rather than a Lit CSSResult or a string. Currently there

Related Documentation & Topics:

• Import Attributes (external)
• Import Attributes Browser Compatiblity Table (external)
• Proposal Import Attributes (external)
• Import JSON, CSS and more with import attributes (external)
• Using CSS Module Scripts to import stylesheets (external)
  • NOTE: The syntax of the import assertions proposal in this article was deprecated in favor of import attribtues which uses with rather than assert.
• Build Tools
  • rollup-plugin-lit-css
  • esbuild-plugin-lit-css
  • lit-css-loader
  • vite-plugin-lit-css

• Scopes styles to the shadow root
• Scopes the DOM to the shadow root
  • Can't be targeted by querySelector calls from outside the shadow root
• Enables slotting content with the <slot> element
• Exposes an API for CSS with CSS Custom Properties and CSS Shadow Parts

Related Documentation & Topics:

• DOM Encapsulation
• Working with Shadow DOM
• How to style your Lit elements (video)

You can turn off the Shadow DOM by overriding the createRenderRoot() method and setting the render root to the element itself.

Related Documentation & Topics:

• Implementing createRenderRoot()

You can slot a component into another component's shadow DOM by using the <slot> element. If you're familiar with React, this is similar to props.children.

Related Documentation & Topics:

• Slots
• Working With Shadow DOM
• How to style your Lit elements (video)
• How to Build a Carousel in Lit (video)
• Build an Animated Carousel Tutorial

Slotted components use the browser's native Shadow DOM projection features. In order to keep strong, performant, and encapsulated styles, the browser vendors have placed restrictions on styling slotted content.

You can style directly-slotted elements with the ::slotted() pseudo-selector. If you would like to style children of slotted content, you should use CSS Custom Properties.

Related Documentation & Topics:

• Styling the Component's Children
• Build an animated carousel element tutorial
• How to style your Lit elements (video)
• How to build a Carousel in Lit (video)

You can set shadow root options passed to Element.attachShadow() by overriding the static shadowRootOptions member.

Related Documentation & Topics:

• Setting shadowRootOptions
• Element.prototype.attachShadow():options (external)
• delegatesFocus (external)

Reactive properties are properties within a component that automatically trigger a re-render when they change. These properties can be set externally, from outside the component's boundary.

They also handle attributes by accepting them and converting them into corresponding properties.

You can define a reactive property with the@property decoratorstatic properties = { propertyName: {...}} code block and initializing them in the constructor().

Related Documentation & Topics:

• Reactive Properties
• Public reactive properties
• Attributes
• Custom property accessors
• Customizing change detection
• Reactivity Tutorial
• Custom Attribute Converters Tutorial
• What Are Elements Video
• Introduction to Lit - Reactive Properties Video

Reactive state is a property that is private to the component and is not exposed to the outside world. These properties are used to store internal state of a component that should trigger a re-render of the Lit lifecycle when they change.

You can define a reactive property with the@state decoratorstatic properties = { propertyName: {state: true, ...}} code block and setting the state: true flag in the property's info. You can initialize them in the constructor().

Related Documentation & Topics:

• Reactive Properties
• Internal Reactive State
• Customizing change detection
• Reactivity Tutorial
• What Are Elements Video
• Introduction to Lit - Reactive Properties Video

Arrays are objects in JavaScript, and Lit's default change detection uses strict equality to determine if an array has changed. If you need to re-render a component when an array is mutated with something like .push() or .pop(), you will need to let Lit know that the array has changed.

The most common ways to do this are:

• Use the requestUpdate() method to manually trigger a re-render
• Create a new array / object reference

Related Documentation & Topics:

• Lifecycle - Triggering an update
• Rendering Arrays
• Reactivity Tutorial - Triggering an update
• Working With Lists Tutorial

In advanced cases, you may need to convert an attribute value to a property in a special way and vice versa. You can do this with a custom attribute converter.

Related Documentation & Topics:

• Reactive properties - Providing a custom converter
• Reactive properties - Using the default converter
• Attributes
• Custom Attribute Converters Tutorial
• Reactive Properties
• Public reactive properties
• Custom attribute converter snippet

Sometimes it is helpful to make a property that is derived from other properties or state. The simplest way you can do is is with a native getter.

Related Documentation & Topics:

• Reactive Properties
• Custom Property Accessors
• get - MDN (external)
• set - MDN (external)

If you have multiple reactive properties that depend on each other, you can reconcile their values in the Lit's willUpdate() lifecycle method.

willUpdate() is a good place to reconcile values between properties that can also run on the server since willUpdate() is called during Lit SSR's server-side rendering.

• Lifecycle - willUpdate()
• What happens when properties change
• Reactive Properties
• Authoring components for Lit SSR

If you have reactive properties that depend on a browser API (like localStorage for example), you can reconcile their values in the Lit's update() lifecycle method.

update() is a good place to reconcile values between properties that need to access Browser APIs or the DOM. update() happens before render.

Related Documentation & Topics:

• Lifecycle - update()
• What happens when properties change
• Reactive Properties
• Authoring components for Lit SSR

If you have multiple reactive properties that depend on calculations from the component's rendered DOM, you can reconcile their values in the Lit's updated() lifecycle method.

updated() is a good place to reconcile values between properties that need to since updated() is called after the component has rendered its template. Though it is highly recommended to not update Reactive Properties in updated() unless necessary as it may trigger re-renders after a render has just completed. Lit is fast, but this could still be unnecessary work.

Related Documentation & Topics:

• Lifecycle - updated()
• Getting An Element Reference
• What happens when properties change
• Reactive Properties
• Authoring components for Lit SSR

There are two lifecycles in Lit, the native Web Component lifecycle and the lifecycle that Lit adds on top of it to help handle property and state changes.

There are more lifecycle events which can be found in the documentation, but the ones you would normally use are the following and this is their general order:

1. constructor – (Native custom element lifecycle)
2. connectedCallback – (Native)
3. willUpdate – (Lit lifecycle)
4. update – (Lit)
5. render – (Lit)
6. firstUpdated – (Lit)
7. updated – (Lit)
8. disconnectedCallback – (Native)

Related Documentation & Topics:

• Lifecycle
• Lifecycle diagram

• Runs when the element is created via:
  • document.createElement('my-element')
  • element.innerHTML = '<my-element></my-element>'
  • new MyElement()
  • etc.
• Is native browser callback
• Requires call to super()
• A good place to set initial properties
• Do NOT require parameters in the constructor or modify DOM

• May run on the server. (This has not been finalized.)
• Runs when the element is added to the DOM via:
  • element.appendChild(element)
  • element.innerHTML = '<my-element></my-element>'
  • etc.
• Is native browser callback
• Requires call to super.connectedCallback()
• Can run multiple times, but a good place to set up event listeners to external elements like document.

• Runs on the server – do NOT access the DOM or browser APIs
• Is NOT a native browser callback (a Lit-specific method)
• Does NOT require call to super.willUpdate()
• A good place to set up properties that depend on other properties

• Runs after willUpdate
• Is NOT native browser callback (a Lit-specific method)
• Typically requires call to super.update() AFTER custom logic
• A good place to update properties that depend on other properties that depend on DOM

• Is NOT a native browser callback (a Lit-specific method)
• Does NOT require call to super.render()
• Runs on the server - do NOT access the DOM or browser APIs

• Runs after the first render
• Is NOT a native browser callback (a Lit-specific method)
• Does NOT require call to super.firstUpdated()
• A good place to perform initializations that require access to the component's rendered DOM

• Runs after render and firstUpdated
• Is NOT a native browser callback (a Lit-specific method)
• Does NOT require a call to super.updated()
• A good place to do some updates that require the component's rendered DOM or to update properties that depend on the rendered DOM
• Avoid setting reactive properties in this lifecycle as doing so may trigger unnecessary re-renders. Try to do them in willUpdate or update if possible.

• Is called AFTER the element is removed from the DOM
• Is native browser callback
• Requires call to super.connectedCallback()
• A good place to clean up event listeners

All Lit elements have asynchronous lifecycles. The reason for this is so that property changes (e.g. el.foo = 1; el.bar = 2;) are batched for efficiency and correctness.

You need to wait for the updateComplete promise to resolve before you can be sure that the element has finished updating its DOM.

Related Documentation & Topics:

• Lifecycle
• updateComplete()
• requestUpdate()
• Getting an Element Reference
• Getting an Element Reference After Update

If you need to perform an asynchronous task in a Lit Element. You may want to use the @lit/task package. It handles marrying basics of managing asynchronous and the Lit lifecycle.

The following example fetches a Pokemon by ID from the PokeAPI based on pokemon name. To do so you:

1. Initialize the task with new Task(...)
2. Task is a Reactive Controller, so you pass it a reference to the Reactive Element (this)
3. Write an async function that fetches and returns the data
4. Give Task a function that will return the reactive properties that Task relies on
5. Render all the states of the Task in the render() method with Task.prototype.render()

Related Documentation & Topics:

• Asynchronous Tasks
• Lit Labs – Task (video)
  • NOTE: This video was published before Task had graduated from Labs.
• Reactive Controllers – Asynchronous Tasks

A common pattern is to add event listeners to the host element in the constructor(). There is no need to remove these listeners as they are automatically cleaned up by the browser's garbage collector when the element is no longer referenced.

Related Documentation & Topics:

• Lifecycle
• Events
• Authoring components for Lit SSR
• A complete guide on shadow DOM and event propagation (external)

A common pattern is to add event listeners to the to global nodes, like document or window, in the connectedCallback and remove them in the disconnectedCallback.

Related Documentation & Topics:

• Lifecycle
• Events
• Authoring components for Lit SSR
• A complete guide on shadow DOM and event propagation (external)

The simplest way to pass data down is to use properties and attributes.

For example, you can pass data down to child components using property bindings like this:

.name=${'Steven'}

For boolean attributes, use a question mark instead of a period, like this:

?programmer=${true}.

You generally want to expose your component's external attribute and property API with@property() instead of @state()static properties = {propName: {state: false}}.

Related Documentation & Topics:

• Expressions
• Expressions – Attribute Expressions
• Expressions – Property Expressions
• Event communication between web components (video)

To send data up the tree to ancestors, you can dispatch custom events. To emit an event, use Element.dispatchEvent().

dispatchEvent() takes an event object as the first argument. Construct a custom event object like this:

new CustomEvent('event-name', {detail: data, bubbles: true, composed: true})

Provide data you want to pass to ancestors in the detail property of the event, and ancestors can react to the event by adding an event listener to the component like this:

@event-name=${this.eventHandler}

If you want an event to bubble through shadow Roots, set composed: true.

Related Documentation & Topics:

• Event communication between web components (video)
• A complete guide on shadow DOM and event propagation (external)
• Expressions
• Expressions – Event listener expressions
• Events
• Customizing event listener options

If you need to pass data down to a subtree without using properties or "prop drilling", you might want to use @lit/context.

Related Documentation & Topics:

• Context
• WCCG Context Community Protocol (external)

The @query decorator allows you to access a reference to a single element in the component's shadow DOM using the syntax of ShadowRoot.prototype.querySelector().

In JavaScript, you can access the element using this.shadowRoot.querySelector().

• @query
• @queryAll
• @queryAsync
• Lit lifecycle

The ref() directive is a lit-html-specific method to acquire an element reference. The ref() directive is a good alternative when:

• You can't use the @query decorator (or its JS equivalent)
• You cannot determine when an element will be rendered
• You need to pass element references from a child to a parent component (not common)
• You're migrating from another framework like React
• You need to run a function when the referenced element changes

Related Documentation & Topics:

• Built-in Directives – ref
• Templates – Element Expressions

The @queryAsync decorator is just like the @query decorator, but it waits for the current host element to finish its update before resolving. This is useful when you need to access an element that is rendered asynchronously by a change in the component's state.

The JavaScript equivalent awaits the this.updateComplete promise before calling this.shadowRoot.querySelector().

Related Documentation & Topics:

• @queryAsync
• updateComplete
• getUpdateComplete()
• Lit lifecycle
• @query
• @queryAll
• Waiting for an update

Shadow DOM uses the <slot> element which allows you to project content from outside the shadow root into the shadow root. You can access slotted content using the@queryAssignedElements decoratorHTMLSlotElement.assignedElements() method.

You give it a slot name to access, and the element selector to filter for.

Related Documentation & Topics:

• Accessing Slotted Children
• Slots
• assignedElements - MDN (external)
• HTMLSlotElement - MDN (external)
• <slot> - MDN (external)

Signals are data structures for managing observable state. They either store a value or compute a value based on other signals. The Lit project tries to conform to the Signals standard proposal via the @lit-labs/signals package in order to provide a cross-framework standard for reactive state management solution.

The most common way to use signals in Lit is to use the SignalWatcher mixin. When an accessed signal value changes, SignalWatcher will trigger the Lit element update lifecycle. This includes signals read in shouldUpdate(), willUpdate(), update(), render(), updated(), firstUpdated(), and reactive controller's hostUpdate() and hostUpdated().

Related Documentation & Topics:

• Signals docs
• Lit lifecycle
• @lit-labs/signals npm package (external)
• Signals standards proposal (external)

The watch() directive allows you to pinpoint exactly where a signal should update the DOM without re-triggering the lit-html re-render. What this means is that using the watch() directive will not trigger the render() unless it triggers the change of a traditional Lit Reactive Property.

Related Documentation & Topics:

• The watch() directive (external)
• Reactive Properties
• Signals docs
• Lit lifecycle
• @lit-labs/signals npm package (external)
• Signals standards proposal (external)

The @lit-labs/signals package also provides an html template tag that can be used in place of Lit's default html tag and automatically wraps any signals in the template with a watch() directive.

Related Documentation & Topics:

• The html tag and withWatch() (external)
• the SignalWatcher() mixin
• The watch() directive

Sometimes you need to derive a value from other signals. You can do this with a computed() signal.

Related Documentation & Topics:

• Signals docs
• @lit-labs/signals npm package (external)

The official signal-utils package currently provides an experimental effect() function that allows you to react to signal changes and run side effects.

Related Documentation & Topics:

• Signals docs
• @lit-labs/signals npm package (external)
• The changedProperties map
• signal-polyfill – Creating a simple effect (external)

If your component needs to share a global state with another component and you do not need your component to be compatible with Lit's declarative event listener syntax, you can use a shared signal to share state across components.

Here is the scoreboard example from the Dispatch Events Up section, but using shared signals.

Related Documentation & Topics:

• Signals docs
• @lit-labs/signals npm package (external)
• Data Flow and State Management

Edit this page