HTML data-* Attributes – Standard Custom Data Attributes

Definition and Usage

The data-* attributes are standard HTML 'custom data attributes' beyond those predefined by HTML.
They are created by combining the data- prefix with a custom name, allowing you to store custom data in the attribute's value.

Custom data attributes are
used to store custom 'data,' 'state,' 'annotations,' and similar information for a page or application.
They are standardized HTML attributes used when no other appropriate standard attribute or element exists.
As global attributes, they can be applied to any HTML element.

They are primarily used in JavaScript and CSS to add dynamic functionality or apply styling.

Basic Example

The following is a simple example of using custom data attributes.

This example demonstrates how to use custom data attributes with JavaScript to display basic product information. Clicking the 'View Product Details' button displays an alert showing the product's details.

HTML

<!-- The data-* attributes are used to store product information.
     Each attribute represents:
     product name (data-name),
     price (data-price),
     stock (data-stock),
     and color (data-color).
-->
<div 
    id="product-12345"
    data-name="Sneakers"
    data-price="10000"
    data-stock="5"
    data-color="red">
    Sneakers
</div>

<!-- The button includes a data-product-id attribute
     that identifies the corresponding product ID.
-->
<button
    type="button"
    id="product-details"
    data-product-id="product-12345">
    View Product Details
</button>

JavaScript

const viewDetails = document.getElementById("product-details");

viewDetails.addEventListener("click", function() {
    const productId = this.dataset.productId;
    const product = document.getElementById(productId);

    /* Retrieves product name, price, stock, and color
       using data attributes from the product element. */
    const productName = product.dataset.name;
    const price = product.dataset.price;
    const stock = product.dataset.stock;
    const color = product.dataset.color;
    
    /* Combines the retrieved product information into a string
       and displays it in an alert dialog. */
    const msg = "Product Name: " + productName +
                "\nPrice: " + price + " KRW" +
                "\nStock: " + stock + " pcs" + 
                "\nColor: " + color;          
    alert(msg);
});

This example demonstrates how to use data attributes to store additional information in HTML elements.
It also helps you understand how custom data attributes and JavaScript work together to create interactive behavior.

Quick Note! 👀
Even if you are not familiar with JavaScript, understanding the purpose of data attributes will greatly help you better understand HTML.

Purpose of Use

The data-* attributes are designed to allow custom data to be added to HTML elements in a standardized way, without the need for non-standard elements, semantically inappropriate attributes, or unnecessary workarounds.
By using these attributes, developers can easily attach their own data to HTML elements in a consistent manner.

Naming Rules for Data Attributes

The rules for naming the data-* attribute—specifically the * part that follows the data- prefix—are as follows:

It must not contain a colon (:, U+003A).
It must not contain uppercase letters.
It must not start with xml, regardless of case.

Using Data Attributes in CSS

Because data attributes are HTML attributes, they can be targeted using CSS selectors.

CSS

[data-name] { /* Targeted using a CSS attribute selector */
    padding: 1em;
    background-color: yellowgreen;
}
[data-color="red"] { /* Targeted using a CSS attribute selector */
    color: red;
}

You can target data attributes using CSS attribute selectors, such as [attribute] and [attribute="value"].

Things to Keep in Mind When Using CSS

Consider the following example:

HTML

<style>
    [data-text]::before {
        content: attr(data-text) ": ";
        font-weight: 600;
        color: red;
    }
</style>
<p data-text="Note">
    Do not store content that should be visible and accessible in data attributes!
</p>

CSS ::before Pseudo-Element

CSS content Property

In the rendered result, "Note:" is displayed on the screen using the value of the data attribute through CSS. This creates accessibility issues.

As shown in the example above, avoid using data attributes and CSS to display content that must be visible to users and accessible to assistive technologies. Such content is often inaccessible to screen readers for users with visual impairments, and search engines may also fail to index it.

Browser Compatibility

Browser compatibility for the data-* Attributes
Attributes	Desktop Chrome	Desktop Edge	Desktop Firefox	Safari
`data-*`	7	12	6	5.1

Specifications

Specification for the data-* Attributes
Specification
`data-*`	HTML Standard #attr-data-*