How do you read and write a data-* attribute from JavaScript through an element's dataset property, and what surprises people about the values and the names?

## What dataset is HTML reserves any attribute whose name starts with `data-` for author-defined data, and the DOM exposes them as one object: `element.dataset`, a `DOMStringMap`. It is a live view, not a snapshot — reading a key reads the attribute right now, writing a key writes the attribute right now, and the two APIs are fully interchangeable: ```js el.dataset.userId === el.getAttribute('data-user-id'); // same storage ``` ## Name translation, in both directions Going from attribute to key, the `data-` prefix is dropped and each `-` that is followed by an ASCII lowercase letter is removed with that letter uppercased. So `data-user-id` → `userId`, `data-x` → `x`, and `data-item-2` → `item-2` — the dash before a digit survives, which means that one is only reachable as `el.dataset['item-2']`. Going from key to attribute, the rule runs backwards: each ASCII uppercase letter becomes `-` plus its lowercase form, and `data-` is prepended. This is the surprising direction: ```js el.dataset.userID = 'x'; el.outerHTML; // <div data-user-i-d="x"></div> el.dataset.userID; // "x" — round-trips consistently el.dataset.userId; // undefined — a different attribute ``` Nothing is wrong there; the mapping is bijective. It just means the attribute you see in DevTools is not the one you expected, and any CSS or server-side code that looks for `data-user-id` will miss it. Pick one canonical spelling and stay with it. One case actually throws: setting a key that contains a `-` immediately followed by a lowercase letter is a `SyntaxError`, because that key could not be produced by the forward mapping and so would not round-trip. ```js el.dataset['my-name'] = 1; // SyntaxError ``` ## Everything is a string An attribute value is a string, full stop, so `dataset` stringifies on write and hands back a string on read: ```js el.dataset.count = 3; typeof el.dataset.count; // "string" el.dataset.count + 1; // "31" — concatenation, not addition Number(el.dataset.count) + 1; // 4 el.dataset.flag = false; el.dataset.flag; // "false" — a truthy string! ``` That last line is the one that reaches production. `if (el.dataset.flag)` is true for `"false"`, because a non-empty string is truthy. Compare explicitly (`=== 'true'`) or store presence rather than a value. Objects fare worse: `el.dataset.user = {id: 1}` stores the string `"[object Object]"`. If you genuinely need structured data in an attribute, serialize deliberately with `JSON.stringify` on the way in and `JSON.parse` on the way out — and accept that the whole payload is now visible in the page source and gets re-parsed on every read. ## Missing keys, and deletion Because `dataset` is an object view, an absent attribute reads as `undefined`. That differs from `getAttribute('data-missing')`, which returns `null`. Both are falsy, so the distinction rarely bites in an `if`, but it matters for `??`, for `=== null` checks, and for anything that distinguishes the two. Deleting works as you would hope: `delete el.dataset.userId` calls `removeAttribute('data-user-id')`. Setting the key to `undefined` does *not* remove it — it writes the string `"undefined"`. ## When to reach for it, and when not to `data-*` is the right tool for small, string-shaped identifiers that genuinely belong to the markup — a row's record id, a variant name, a state token a CSS attribute selector also wants to match on (`[data-state="open"]`). It survives serialization, it is inspectable in DevTools, and it needs no side table. It is the wrong tool for anything large, structured, frequently-changing, or private. The data is in the document: visible to the user, copied by anything that reads the subtree back as HTML, re-stringified on every write, and re-parsed on every read. Rich per-element state is better kept in JavaScript-side structures keyed by the element, where the values keep their types and never touch the markup. `getAttribute('data-...')` remains available and is the escape hatch for names `dataset` cannot express, and for code that wants the `null`-on-missing behaviour.