Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 39 ยท Custom Elements

Properties and Attribute Reflection

Give custom elements a JavaScript API with properties, getters and setters, and learn when and how to reflect properties to attributes without causing loops.

Attributes are for HTML authors. Properties are for JavaScript. A good component offers both, and keeps them in sync for the values where that makes sense. Native elements set the pattern: input.value and <input value>, img.src and <img src>, details.open and <details open>.

Why properties matter

Attributes can only carry strings. Properties can hold anything: numbers, booleans, arrays, objects, functions, dates. If your component needs a list of items, a callback, or a large data object, a property is the only sensible channel.

A property that takes an array

The setter copies the array so outside code cannot mutate the internal state by accident, and it re-renders. Because items is an accessor, assignment triggers your code, exactly like a built-in property.

Getters and setters

Use JavaScript accessors to validate and to react:

JavaScript
get count() { return this.#count; }
set count(value) {
  const n = Math.max(0, Number(value) || 0);
  if (n === this.#count) return;
  this.#count = n;
  this.#render();
}

Plain class fields also work, but a field gives you no hook when someone assigns it. Accessors are the right tool for any property that must update the UI.

Reflecting a property to an attribute

Reflection means that changing one side updates the other. Built-in elements reflect many properties: set link.hidden = true and the hidden attribute appears; add hidden in HTML and link.hidden reads true.

Reflect when the value is simple (string, number, boolean) and when the attribute has a purpose, such as CSS selectors like :host([open]) or HTML configuration. Do not reflect large objects.

The classic implementation reads and writes the attribute, and lets attributeChangedCallback update the view:

A reflecting open property

There is a single source of truth: the attribute. The property getter reads it, the setter writes it, and CSS (:host(:not([open]))) does the visual work. No second variable can fall out of sync.

Direction matters: avoiding infinite loops

If the property setter changes the attribute and attributeChangedCallback calls the setter again, you get a loop. Break it by choosing one of two designs:

  1. Attribute is the source of truth. The setter only writes the attribute; the callback does the real work. (The example above.)
  2. Property is the source of truth. The setter stores the value, updates the view and writes the attribute; the callback ignores changes when the attribute already matches the property.
JavaScript
attributeChangedCallback(name, oldValue, newValue) {
  if (name === "count" && Number(newValue) !== this.#count) {
    this.count = newValue;        // goes through the setter
  }
}

The comparison stops the cycle.

Properties set before the element is defined

One well-known trap: if a script sets el.items = [...] on a tag before its definition has loaded, the value becomes an ordinary own property on the not-yet-upgraded element and shadows your accessor after the upgrade. Fix it in the constructor by checking for an own property and moving it:

JavaScript
constructor() {
  super();
  this.#upgradeProperty("items");
}

#upgradeProperty(name) {
  if (Object.prototype.hasOwnProperty.call(this, name)) {
    const value = this[name];
    delete this[name];
    this[name] = value;
  }
}

This tiny helper appears in many production components. The later lesson on upgrading shows the full story.

Which side wins in naming?

Attribute names are lowercase, properties are camelCase. Keep them parallel: max-items maps to maxItems, readonly to readOnly. Follow built-ins where an equivalent exists.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use a property instead of an attribute for an array of data?

    Attribute values are text. Properties carry arrays, objects and functions directly.
  2. 2. In the reflecting open example, where does the state live?

    Using the attribute as the single source of truth avoids two variables getting out of sync.
  3. 3. What can cause an infinite loop between a setter and attributeChangedCallback?

    Guard with a comparison or make only one side write.
  4. 4. What problem does the upgradeProperty helper solve?

    An early assignment creates an own data property that hides the class accessor, so the helper re-assigns it through the accessor.

Summary

  • Offer properties for JavaScript users and attributes for HTML authors.
  • Use accessors when assigning must trigger validation or rendering.
  • Reflect simple values (strings, numbers, booleans); do not reflect big objects.
  • Pick one source of truth to avoid loops, often the attribute for booleans.
  • Re-apply properties that were set before the upgrade.

Next: Customized Built-in Elements