Accessing data-* Attributes with `dataset`

Why it exists

Before dataset, developers had to manually parse attribute names with getAttribute('data-user-id') and setAttribute. The dataset property provides a cleaner, object-like API for this common task, reducing boilerplate code and improving readability by creating a direct bridge between HTML attributes and JavaScript properties.

The mental model

Think of dataset as a live-updating JavaScript object that mirrors an element's data- attributes. It's not a static copy. When you change a property on element.dataset, the corresponding data- attribute in the HTML is immediately added, updated, or removed.

How it works

The browser handles the name conversion between HTML and JavaScript. In HTML, attributes are written in kebab-case (e.g., data-user-id). In JavaScript, you access this via dataset, where the data- prefix is dropped and the name is converted to camelCase (e.g., element.dataset.userId). Any uppercase letters in the original HTML attribute name are converted to lowercase before this transformation. For example, an element has a property div.dataset.itemId which returns the string "123". You can also write to it: div.dataset.lastUpdated = '2024-05-20' will add a data-last-updated="2024-05-20" attribute to the div.

When to use it

Use dataset to store simple, non-critical string data directly on an element. It's perfect for holding metadata that your JavaScript needs for presentation logic, like a record ID, a component's state ('open', 'closed'), or a URL for an API call, without needing a separate JS object to track it.

When not to use it

Avoid storing complex data (objects, arrays), sensitive information, or anything that should be part of your application's main state management system. Since all values are stored as strings, you must manually parse them into other types like numbers or booleans. Remember that this data is publicly visible in the DOM.

One canonical example

Given the HTML <button id="userBtn" data-user-id="42" data-action="fetch-details">View User</button>, you can access its data in JavaScript:

const btn = document.getElementById('userBtn');

console.log(btn.dataset.userId); // "42" console.log(btn.dataset.action); // "fetch-details"

// Now, let's add a new attribute from JavaScript:

btn.dataset.hasBeenClicked = 'true';

// This adds data-has-been-clicked="true" to the button element in the DOM.