Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 38 ยท Custom Elements

Attributes vs Properties in Custom Elements

Learn the difference between HTML attributes and JavaScript properties, how to sync them with getters and setters, and why Lit treats them as two ways to set the same value.

Every HTML element has two ways to hold data. Attributes are the strings you write in markup: <input value="hi">. Properties are the JavaScript values on the element object: input.value. They are often linked, but they are not the same thing, and the difference is the source of many web component bugs.

A good custom element supports both. Authors writing HTML use attributes. Code and frameworks set properties, because properties can hold any JavaScript value, not only strings. This lesson shows how to wire the two together by hand. Lit does the same job with one declaration, which you will see at the end.

Two different storages

Attributes live in the DOM tree and are always strings. Properties live on the JavaScript object and can be numbers, objects, arrays, functions, or anything else.

Attribute and property are separate

For <input>, the attribute value is only the default value. After the user types or code sets field.value, the property changes and the attribute stays the same. Other built-in properties do mirror their attribute: element.id, element.className and anchor.href stay in sync automatically. Each element decides, and the rules are written down in the HTML standard.

The pattern for custom elements

For your own element, a clean approach is:

  1. Keep the data in a property (a getter and setter pair).
  2. Let an attribute feed the property, through attributeChangedCallback.
  3. Optionally reflect the property back to the attribute, so CSS selectors like [open] keep working.

Here is a rating element that follows this pattern. The attribute is a string, so the property converts it to a number.

A star rating with attribute and property

Study the flow. Setting stars.value = 4 runs the setter, which clamps the number, stores it, writes the attribute and renders. Writing the attribute triggers attributeChangedCallback, which calls the setter again with the same value, and the guard if (n === this.#value) return stops the loop. Without that guard you would get infinite recursion, a very common mistake.

flowchart LR
  A["Attribute<br/>value=&quot;3&quot;"] -->|attributeChangedCallback| P["Property<br/>this.value = 3"]
  P -->|"reflect (optional)"| A
  P --> R["render()"]

Attributes feed the property; the property can reflect back. The guard stops the loop.

Types: strings, numbers, booleans

Attributes carry strings, so each type needs a convention:

Type Attribute form Property form
String title="Hi" "Hi"
Number max="5" converted with Number() 5
Boolean present or absent: <x-box open> true or false
Object or array not practical; JSON in a string is a last resort the real value

Boolean attributes follow HTML: the presence of the attribute means true, whatever its value. disabled="false" is still disabled. To turn it off, remove the attribute with removeAttribute or toggleAttribute.

A boolean attribute

Here the property is a thin wrapper over the attribute: the attribute is the single source of truth, so there is no second copy to keep in sync. That is a good choice for simple booleans and strings.

Objects and arrays: properties only

You cannot put a list of products in an attribute without turning it into JSON. For rich data, give the element a property and set it from JavaScript:

JavaScript
const table = document.querySelector("data-table");
table.rows = [{ name: "Ada" }, { name: "Grace" }]; // property, not attribute

Frameworks differ in how they pass data to custom elements: some set attributes, some set properties. Offering both for simple values and properties for complex data makes your component usable everywhere.

How Lit does it

Everything you wrote by hand in this lesson, Lit does from one declaration:

JavaScript
static properties = {
  value: { type: Number },            // attribute "value" -> Number property
  open:  { type: Boolean, reflect: true }, // property -> attribute
  rows:  { attribute: false },         // property only
};

Lit creates the getter and setter, observes the attribute, converts the string by type, guards against loops, and schedules one render. Attributes, Reflection and Converters in Lit goes through the options in full.

Common mistakes

  • Forgetting the equality guard when reflecting, which causes endless loops.
  • Writing disabled="false" and expecting false. Remove the attribute instead.
  • Reading getAttribute("count") and treating it as a number. It is always a string or null.
  • Setting attributes in the constructor. The standard forbids it for elements created with createElement.
  • Passing objects through attributes. You get [object Object].

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What type is the value returned by getAttribute()?

    Attributes are strings. A missing attribute gives null. Conversion to numbers or booleans is your job.
  2. 2. How does HTML decide that a boolean attribute is true?

    Presence alone means true. disabled="false" is still disabled; remove the attribute to turn it off.
  3. 3. Why is an equality check needed when a property setter writes its own attribute?

    The attribute change calls the callback, which calls the setter again. Returning early when nothing changed ends the cycle.
  4. 4. How should you pass an array of objects to a custom element?

    Properties can hold any value. Attributes are strings, so JSON in an attribute is a poor fit for rich data.

Summary

  • Attributes are strings in the markup; properties are any JavaScript value on the object.
  • A custom element should accept both, with the property as the main API.
  • Use observedAttributes and attributeChangedCallback to feed properties from attributes, and guard against loops when reflecting.
  • Booleans are true when the attribute is present; use toggleAttribute.
  • Lit generates all of this from static properties.

Next: The Template Element