Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 39 ยท Events and Properties

Attributes vs Properties in Custom Elements

Understand the difference between HTML attributes and JavaScript properties on custom elements, when to use each, and how to design a clean public API.

Every custom element has two ways to receive data. Attributes live in the HTML markup and are always strings. Properties live on the JavaScript object and can hold anything: numbers, arrays, objects, functions. Native elements already mix both. <input value="hi"> sets an attribute, while input.value = "hi" sets a property, and the two are not always the same thing.

When you build your own element you decide how the two sides relate. A well-designed component accepts simple values through attributes (so people can write it in plain HTML) and richer values through properties (so frameworks and scripts can pass data directly). This lesson shows how to wire up both sides and where the traps are.

Two doors into the same element

Think of attributes as the door for markup authors and properties as the door for script authors.

flowchart LR
  A["HTML attribute<br/>(string only)"] --> C["attributeChangedCallback"]
  C --> S["Internal state"]
  P["JS property setter<br/>(any type)"] --> S
  S --> R["Render"]

Both doors lead to the same internal state; the element renders from that state.

A good rule: the property is the source of truth, and the attribute is one way of setting it. Attributes are converted to the right type on the way in.

Reading an attribute

Inside a custom element you can read attributes with getAttribute(). It always returns a string or null.

Reading attributes as strings

Note the Number(...) conversion. "3" + 1 would be "31", a classic bug. Always convert attribute strings before doing math.

Exposing properties with getters and setters

To offer a property, define a getter and a setter on the class. The setter is the right place to convert, validate and trigger a re-render.

A property API

The setter clamps the value to the range 0 to 100, so meter.value = 500 gives 100. The component owns its rules; callers cannot put it into an invalid state.

Use private fields (#value) for state behind a property. A public field named value would shadow the setter on the instance and silently bypass your validation.

The upgrade trap

A property set before the element is defined is stored as a plain own property on the not-yet-upgraded element. When the class is later registered, that own property shadows your getter and setter. This happens when a script sets el.value before the component's module has loaded.

The fix is to check for own properties during construction and re-apply them:

JavaScript
connectedCallback() {
  this.#upgradeProperty("value");
}

#upgradeProperty(name) {
  if (Object.hasOwn(this, name)) {
    const early = this[name];
    delete this[name];
    this[name] = early;
  }
}

It looks fussy, but it prevents a famously confusing bug where "the setter never runs". You will see it again in the lesson on lazy loading and distribution.

Which type goes where?

Kind of data Attribute Property
Short text, enum Yes Yes
Number Yes (parse it) Yes
Boolean flag Presence or absence true / false
Array or object No (too awkward) Yes
Function / callback No Yes

Complex data should be a property only. Serializing arrays to JSON inside attributes is possible but hurts readability, and every change forces a parse.

Boolean attributes

HTML booleans work by presence: <button disabled> is true, and the attribute's value is irrelevant. Follow the same convention. Never write disabled="false", because the attribute is still present and therefore true.

Boolean attribute convention

The third chip still shows the star, because hasAttribute only checks presence. That is the platform's own behavior, so matching it keeps your elements predictable.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What type does getAttribute() always return?

    Attributes are strings in the DOM. getAttribute returns that string, or null when the attribute does not exist.
  2. 2. Why use a private field behind a property?

    A public instance field with the same name replaces the accessor on that instance, so your setter logic never runs.
  3. 3. Which markup turns a boolean attribute off?

    Boolean attributes are true when present, whatever their value. Only removing the attribute makes them false.
  4. 4. Where should an array of objects normally be passed?

    Rich data belongs on properties. Attributes are strings, so structured data would need serializing and parsing.

Summary

  • Attributes are strings in markup; properties are any JavaScript value on the object.
  • Treat the property as the source of truth and convert attributes into it.
  • Validate and re-render inside setters; keep state in private fields.
  • Boolean attributes mean true by presence.
  • Properties set before the element is defined must be re-applied after upgrade.

Next: Reflecting Attributes and Observed Changes