Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 38 ยท Reactive Properties

Reactive Properties and Internal State

Learn how Lit reactive properties and internal state trigger re-renders, how static properties work, why class fields break reactivity, and how to use hasChanged.

A Lit component is a function of its data: you describe the UI in a render() method and Lit re-runs it whenever the data changes. The data that Lit watches is called reactive properties. Change one, and Lit schedules an update; change a plain field, and nothing happens.

This lesson covers the two kinds of reactive data (public properties and internal state), how to declare them without decorators, the one class-field trap that bites almost everybody, and how to control when a change counts as a change.

Declaring reactive properties

You declare reactive properties in a static properties object. Each key becomes a property on the element with a getter and a setter that Lit generates. The setter compares the new value with the old one and, if they differ, requests an asynchronous update.

A reactive property

Press the button and watch the console: render() runs once for the first paint and once per change. You never call render() yourself, and you never touch the DOM; assigning card.name is enough.

The type option only matters for attributes (the next lesson, Attributes and Converters, explains it). For a property you only set from JavaScript you can even write {}.

Public properties versus internal state

Lit distinguishes two kinds of reactive data:

Kind Declared with Visible to users of the element? Typical use
Public property { type: ... } Yes: part of the API, can map to an attribute label, disabled, value
Internal state { state: true } No: private by convention open, hovering, loading, cached results

Internal state is still reactive. The difference is intent: public properties are an API you promise to keep stable, while state is an implementation detail. Lit does not create an attribute for state, so HTML authors cannot set it by accident.

Property plus internal state

By convention internal state starts with an underscore. The attribute check prints false because state never reflects to an attribute.

Two kinds of reactive data

Public property Part of the API; can be an attribute
Internal state state: true; private to the class

Both trigger a re-render when changed.

1 / 2

Updates are batched

When you change several properties in a row, Lit does not render several times. The first change queues a microtask; all changes made before that microtask runs are folded into a single update.

Batching

Because updates are asynchronous, reading the DOM straight after setting a property shows the old DOM. Await el.updateComplete first; the update lifecycle lesson goes deeper.

The class-field trap

Lit installs its getter/setter pair on the class prototype. A modern JavaScript class field such as name = "x" defines an own property on the instance, which shadows that accessor. The value is stored, but Lit never hears about it, so changes no longer re-render.

JavaScript
class Broken extends LitElement {
  static properties = { count: { type: Number } };
  count = 0;                 // BAD: shadows the reactive accessor
}

class Fixed extends LitElement {
  static properties = { count: { type: Number } };
  constructor() {
    super();
    this.count = 0;          // GOOD: goes through the generated setter
  }
}

Set defaults in the constructor when you use static properties. Decorators (@property() in TypeScript) work with class fields because the compiler is configured so that the decorator wraps the field; see Tooling and Build Setup for that setup.

If a Lit component "does not update", check for a class field on a declared property first. It is the single most common cause.

Objects and arrays: replace, do not mutate

Lit's default change detection is a strict inequality check (!==). Mutating an array in place leaves the same reference, so Lit sees no change.

Mutate versus replace

If you really must mutate, call this.requestUpdate() afterwards. Immutable updates are usually cleaner, and they make hasChanged checks (below) cheap.

Custom change detection with hasChanged

Each property can supply its own hasChanged(newValue, oldValue) function. Return true to schedule an update. Use it when strict equality is wrong, for example to ignore tiny changes or to compare by value.

hasChanged

The property value changes immediately either way; hasChanged only decides whether a render is queued.

Common mistakes

  • Declaring a field with = and expecting reactivity (see the trap above).
  • Forgetting super() in the constructor, which throws before anything runs.
  • Storing derived values as state. Compute them inside render() instead, or in willUpdate (lifecycle lesson).
  • Making everything public. Prefer state: true unless an outside caller needs it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does { state: true } in a property declaration mean?

    Internal state is reactive like any property, but it is not part of the public API and never maps to an attribute.
  2. 2. You declare static properties = { n: {} } and then write n = 0; as a class field. What happens?

    A class field defines an own property on the instance, hiding the prototype accessor Lit generated. Set defaults in the constructor instead.
  3. 3. A component keeps items as an array and calls this.items.push(x). Why does the UI not update?

    Lit compares with !==. Assign a new array (for example with spread) or call requestUpdate() after mutating.
  4. 4. You set three reactive properties one after another. How many renders occur?

    The first change queues an update; the rest are folded into it before it runs.

Summary

  • Reactive properties are declared in static properties; changing them schedules an asynchronous, batched render.
  • Use public properties for the element's API and state: true for internal data.
  • Set defaults in the constructor, not with class fields, unless a decorator toolchain is configured.
  • Replace arrays and objects instead of mutating them, or call requestUpdate().
  • hasChanged customizes what counts as a change.

Next: Attributes and Converters