Attributes & properties

Two places for information

An element is one piece of a web page, such as a button or a text box. Each element can keep information in two places:

• An attribute is a name and a value written in the HTML, such as id="save" or value="Ada". Its value is always text.
• A property is a field on the element's object in JavaScript, such as button.id or input.value. The browser makes one object for each element. All these objects together are called the DOM.

Why two places? A page changes while people use it. A user types in a box. A user ticks a checkbox. Your code changes a value.

• Attributes usually keep the starting setup, as text.
• Properties usually keep how things are right now. A property can also be another type: true or false, a number, or an object.

const input = document.createElement("input");
input.setAttribute("value", "Ada");
input.value = "Grace";
console.log(input.getAttribute("value"));
console.log(input.value);

Line 1 makes a new text box, an input element. Line 2 sets its value attribute to Ada. Line 3 sets its value property to Grace, just as typing would. Line 4 reads the attribute and prints Ada. Line 5 reads the property and prints Grace. The rest of this lesson keeps coming back to this split.

Before this lesson, you should know The browser environment, The DOM tree, Walking & searching the DOM, and Node properties & contents. The next lesson, Creating & changing elements, uses these reads and writes to build new elements.

Four methods work with attributes:

• element.getAttribute(name) reads an attribute. It gives back text, or null if the attribute is not there. null means "no value".
• element.setAttribute(name, value) writes an attribute. It turns the value into text first.
• element.hasAttribute(name) gives true if the attribute is there, and false if it is not.
• element.removeAttribute(name) deletes an attribute.

Upper and lower case don't matter in attribute names on HTML elements. getAttribute("ID") and getAttribute("id") read the same attribute.

const card = document.createElement("article");
card.setAttribute("data-count", 3);
console.log(card.getAttribute("data-count"));
console.log(card.hasAttribute("data-count"));
card.removeAttribute("data-count");
console.log(card.getAttribute("data-count"));
card.setAttribute("color", "teal");
console.log(card.getAttribute("color"));
console.log(card.color === undefined);

Line 2 writes the number 3. The attribute stores it as the text "3", so line 3 prints 3. Line 4 prints true because the attribute is there. Line 5 removes it. Line 6 prints null because the attribute is now gone.

Lines 7 to 9 use a made-up attribute, color. HTML has no color attribute for this element. Line 8 still reads it and prints teal. But the browser makes no property for it, so card.color is undefined and line 9 prints true.

Use hasAttribute when you only need to know if an attribute is there. Use getAttribute when you need its text.

Try the inspector below. It has a real text box and a real checkbox. Type something in the text box first. Then press setAttribute value: only the attribute and the starting value change. Then press write input.value: the text in the box changes.

1const input = document.querySelector("input");2 3input.value;                 // property: current typed text4input.getAttribute("value"); // attribute: default from HTML5input.defaultValue;          // property reflecting that default6 7input.setAttribute("value", "Linus");8input.value = "Grace";

Many built-in attributes are linked to a property. When you change one, the browser updates the other. This link is called reflection: we say the property reflects the attribute.

But the two sides don't always have the same name or the same type. Check the rule for each one you use. In the table below, each row is one attribute. Read across to see what each side gives you.

The next code block tries three of these rules. It first adds a <base> element to the page. A <base> element sets the page's base address: the address that short links like /docs are joined to.

const base = document.createElement("base");
base.href = "https://example.test/app/";
document.head.append(base);
const link = document.createElement("a");
link.setAttribute("href", "/docs");
link.className = "quiet";
link.style.color = "teal";
console.log(link.getAttribute("href"));
console.log(link.href);
console.log(link.className);

• Line 8 reads the href attribute and prints /docs, just as written.
• Line 9 reads the href property and prints https://example.test/docs. The browser joined /docs to the base address.
• Line 10 prints quiet. className is the property for the class attribute, set on line 6.
• Line 7 uses style as an object: link.style.color changes just the color.

The step-through in the next section can't use a real page. So it uses a small plain object that copies how a text box behaves. Here is its full code. A real text box gives the same results.

1function makeInput(defaultValue) {2  return {3    attributes: { value: String(defaultValue) },4    value: String(defaultValue),5    defaultValue: String(defaultValue),6    getAttribute(name) {7      return Object.hasOwn(this.attributes, name) ? this.attributes[name] : null;8    },9    setAttribute(name, value) {10      this.attributes[name] = String(value);11      if (name === "value") this.defaultValue = String(value);12    },13    removeAttribute(name) {14      delete this.attributes[name];15      if (name === "value") this.defaultValue = "";16    },17  };18}19 20const input = makeInput("Ada");21input.value = "Grace";22input.setAttribute("value", "Linus");23console.log(input.value);24console.log(input.getAttribute("value"));25console.log(input.defaultValue);

Lines 1 to 18 build the stand-in text box. Lines 20 to 25 use it. Line 21 acts like typing. Line 22 changes the attribute.

Text boxes and checkboxes are where people get mixed up most. A text box is an input element. It has three values to know:

• input.value is the text in the box now.
• input.getAttribute("value") is the starting text, from the attribute.
• input.defaultValue is a property that also gives the starting text.

A checkbox works the same way:

• checkbox.checked is true if the box is ticked now.
• The checked attribute says whether the box started ticked.
• checkbox.defaultChecked is a property that also gives the starting state.

const checkbox = document.createElement("input");
checkbox.type = "checkbox";
checkbox.setAttribute("checked", "");
checkbox.checked = false;
console.log(checkbox.checked);
console.log(checkbox.defaultChecked);
console.log(checkbox.hasAttribute("checked"));

Line 2 makes the input a checkbox. Line 3 adds the checked attribute, so the box starts ticked. Line 4 unticks it by setting only the property. Line 5 prints false: the box is not ticked now. Lines 6 and 7 print true and true: defaultChecked and the attribute still say it started ticked.

Now step through the stand-in text box from the last section. Watch the attribute and the property split apart at line 21.

1function makeInput(defaultValue) {2  return {3    attributes: { value: String(defaultValue) },4    value: String(defaultValue),5    defaultValue: String(defaultValue),6    getAttribute(name) {7      return Object.hasOwn(this.attributes, name) ? this.attributes[name] : null;8    },9    setAttribute(name, value) {10      this.attributes[name] = String(value);11      if (name === "value") this.defaultValue = String(value);12    },13    removeAttribute(name) {14      delete this.attributes[name];15      if (name === "value") this.defaultValue = "";16    },17  };18}19 20const input = makeInput("Ada");Run21input.value = "Grace";22input.setAttribute("value", "Linus");23console.log(input.value);24console.log(input.getAttribute("value"));25console.log(input.defaultValue);

Sometimes your own code needs to keep a small piece of text on an element, such as a user's ID. Use an attribute whose name starts with data-, like data-user-id. These are called data-* attributes. HTML never uses these names for anything else, so they are safe to use.

JavaScript reads them through element.dataset. The name changes from HTML style to JavaScript style, which is called camelCase:

• Drop data- from the front.
• A dash followed by a small letter becomes that letter as a capital.
• So data-user-id becomes dataset.userId.

It works the other way too. Setting dataset.someValue creates the attribute data-some-value.

const item = document.createElement("li");
item.dataset.userId = 42;
console.log(item.getAttribute("data-user-id"));
console.log(typeof item.dataset.userId);
console.log(Number(item.dataset.userId));

Line 2 sets dataset.userId to the number 42. Line 3 reads the attribute data-user-id and prints 42. Line 4 prints string: the number was stored as text. Line 5 uses Number(...) to turn the text back into a number and prints 42. Only do that when you need to do maths with it.

Anyone can see data-* attributes in the page. Never keep passwords or other secrets in them.

1const card = document.querySelector("[data-user-id]");2 3card.dataset.userId;       // "42"4card.dataset.role;         // "admin"5card.dataset.lastSeen = 7; // creates data-last-seen="7"6delete card.dataset.role;  // removes data-role

Some attributes work like on/off switches. They are called boolean attributes, because true and false are called booleans. Examples are disabled, checked, hidden, and required.

For these, only one thing matters: is the attribute there? If it is there, the feature is on. Its text does not matter. Even "false" or "0" leave it on. To turn it off, do one of these:

• Remove the attribute with removeAttribute.
• Set the property to false, like button.disabled = false.

toggleAttribute(name, on) adds or removes an attribute in one step. If the second value is true, it adds the attribute. If it is false, it removes it.

const button = document.createElement("button");
button.toggleAttribute("disabled", true);
console.log(button.hasAttribute("disabled"));
button.toggleAttribute("disabled", false);
console.log(button.disabled);

Line 2 adds disabled, so line 3 prints true. Line 4 removes it, so line 5 prints false from the disabled property. The second value is handy when you already have a true or false in a variable, such as isSaving.

1const button = document.querySelector("button");2 3button.setAttribute("disabled", "false");4button.hasAttribute("disabled"); // true5button.disabled;                 // true6button.removeAttribute("disabled");7button.disabled = false;8button.toggleAttribute("disabled", true);

Where you will use this

Real code often uses both sides. Use attributes for:

• Starting values and settings written in the HTML.
• ARIA attributes. These describe the page for screen readers and other tools that help people use it.
• Anything a CSS selector should match, like [data-panel].

Use properties for how things are right now, and for values the browser works out, like a full link address. Here is a tab button that shows a panel. It uses both sides:

1const tab = document.querySelector("[data-panel]");2const panelId = tab.dataset.panel;3const panel = document.getElementById(panelId);4 5tab.setAttribute("aria-selected", "true");6tab.disabled = true;7panel.hidden = false;

• Line 2: tab.dataset.panel reads the sticky note. It holds the ID of the panel to show.
• Line 5: setAttribute("aria-selected", "true") writes an ARIA attribute. A screen reader can then say that the tab is selected.
• Line 6: tab.disabled = true sets the property. The browser also adds the disabled attribute.
• Line 7: panel.hidden = false sets the property, so the panel shows now.

Common misconceptions

• “Attributes and properties are the same thing.” Many are linked. But attributes are text from the HTML, usually the starting values. Properties are fields on the live object, usually the values now.
• “setAttribute("value", ...) always changes the text in the box.” Once the user has typed, it only changes the starting value. Set the value property to change the text in the box.
• “disabled="false" means not disabled.” A boolean attribute is on whenever it is there. Its text is ignored.
• “dataset can store numbers and objects.” dataset values are always text. Turn them back with Number(...), or with JSON.parse(...) if you stored JSON text.
• “Every attribute has a property with the same name.” Some properties have a new name, like className. Some have another type, like tabIndex, which is a number. Made-up attributes have no property at all.
• “getAttribute gives undefined when the attribute is missing.” It gives null.

Key takeaways

• Attributes are text written in the HTML, usually the starting values. Properties are fields on the element's live object, usually the values now.
• getAttribute gives text or null. setAttribute turns any value into text.
• Linked pairs don't always match. A property can have a new name (className), another type (tabIndex), or a worked-out value (the full href).
• For text boxes and checkboxes, value and checked are the state now. The attributes, defaultValue, and defaultChecked are the starting state.
• data-* attributes show up in dataset with camelCase names, always as text.
• Boolean attributes are on when they are there. Remove them, or set the property to false, to turn them off.

Up next: Creating & changing elements.