HTML data-* Attributes

HTML data-* Attributes

HTML data-* attributes are global attributes that let you store custom data directly on HTML elements. The asterisk represents a custom name chosen by the author, such as data-id, data-category, or data-user-name.

Syntax

A custom data attribute begins with data- followed by a custom name and an attribute value.

<div data-category="html">HTML Tutorial</div>

In this example, data-category is the custom data attribute and html is its value.

Attribute Names and Values

A custom data attribute must begin with data- and contain at least one character after the hyphen. In HTML, custom data attribute names must not contain ASCII uppercase letters.

<article data-id="125" data-topic="html">
  HTML Attribute Tutorial
</article>

The values are stored as strings and can contain information that is useful to the page or application.

Global Attributes

The data-* attributes are global attributes and can be specified on HTML elements to associate custom information with them.

<p data-status="complete">Tutorial complete.</p>

<button data-action="save">Save</button>

<img src="image.jpg" alt="Example" data-image-id="42">

The custom data normally has no built-in visual effect. It becomes useful when accessed by scripts, selectors, or other page logic.

Using Multiple data-* Attributes

An element can contain more than one custom data attribute.

<article
  data-id="125"
  data-category="html"
  data-level="beginner">
  HTML Tutorial
</article>

Each attribute stores a separate piece of information associated with the element.

Accessing data-* with JavaScript

JavaScript can access custom data attributes through an element's dataset property.

<button id="example" data-topic="HTML">Show Topic</button>

const button = document.getElementById("example");
console.log(button.dataset.topic);

The dataset.topic property corresponds to the HTML data-topic attribute. Individual dataset properties can also be changed with JavaScript, which updates the corresponding HTML data attribute.

data-* and dataset Names

When a custom data attribute is accessed through dataset, the data- prefix is removed and names containing hyphens are converted to camel case.

<div id="user" data-user-name="Alex">User Profile</div>

const user = document.getElementById("user");
console.log(user.dataset.userName);

Using data-* with CSS

Custom data attributes can also be selected with CSS attribute selectors.

<p data-status="complete">Completed tutorial</p>
<p data-status="pending">Pending tutorial</p>

[data-status="complete"] {
  font-weight: bold;
}

This allows styles to be applied according to custom information stored on an element.

data-* and the data Attribute

The data-* attributes are different from the data attribute used by the <object> element.

Common Mistakes

Do not use a bare data- attribute. A custom name must follow the hyphen, such as data-id or data-category.

Do not use custom data attributes when an existing HTML attribute or element already provides the appropriate semantics. The data-* attributes are intended for custom information for which HTML does not provide a more suitable feature.

Do not rely on data-* attributes for content that users need to see or that assistive technologies must be able to access. Important visible information should be included in the document's actual content.

Browser Support

Baseline: Widely available indicates a feature has been supported by core browsers for at least 30 months. At this stage, the feature is considered stable and safe for most websites to use without needing to worry about compatibility issues or fallbacks, as it is supported by the vast majority of users' devices and browser versions.

Custom data-* attributes are widely supported on HTML elements in current core browsers.

Checking Browser Support

For current browser compatibility information, visit Can I Use? . Search for the HTML element or attribute you want to check. You can also narrow your search by entering an element name and attribute name separated by a colon. Search results can include related HTML features, element attributes, input types, APIs, and other technologies, so select the result that most closely matches the feature you are checking.

Try data-* Attributes

The example stores a tutorial topic in a data-topic attribute. Click the button to have JavaScript read the value through the element's dataset property.

Summary

HTML data-* attributes store custom information directly on HTML elements. Each attribute begins with data- followed by a custom name, and JavaScript can access the stored values through the dataset property. Custom data attributes can also be targeted with CSS attribute selectors and should be used for information for which HTML does not provide a more appropriate attribute or element.