HTML data-* Attribute

Introduction

The data-* attributes in HTML provide a way to store custom data private to the page or application. They let you attach extra information to any element without affecting how the page looks, and they are especially useful for JavaScript behavior and CSS styling hooks.

What You’ll Learn

Purpose of data-*

The primary purpose of data-* attributes is to store custom metadata on HTML elements. This data is not shown to users by default and does not change standard rendering. It gives developers a standard, valid way to embed configuration, IDs, state flags, or other values that scripts need.

📝 Syntax

Prefix the name with data- followed by a descriptive identifier:

<div data-example="custom-data">This element has custom data</div>



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

Syntax Rules

• Name format: data- + your name (use lowercase and hyphens, e.g. data-user-id).
• Do not use uppercase letters in the attribute name; browsers normalize them to lowercase.
• Include at least one hyphen after data- (e.g. data-id) to avoid future conflicts with standard attributes.
• Values are always stored as strings in the DOM.

How It Works

In the first example, data-example stores the string custom-data on the <div> element for scripts to read later.

💎 Values

The data-* attribute can hold different kinds of information, but the browser always treats the value as a string:

• Text — data-role="admin"
• Numbers as strings — data-count="5" (parse with Number() in JS)
• Booleans as strings — data-active="true"
• JSON as a string — data-config='{"theme":"dark"}' then JSON.parse()

<div data-price="19.99" data-in-stock="true"></div>



<script>

  var el = document.querySelector("[data-price]");

  var price = parseFloat(el.dataset.price);

  var inStock = el.dataset.inStock === "true";

</script>

Applicable Elements

data-* vs the object data attribute

Examples Gallery

User profile data, and reading or updating values with dataset.

<div id="user" data-user-id="123" data-username="john_doe" data-email="john@example.com">

  <!-- Content for the user profile -->

</div>

<script>

  // Get the value of a data attribute

  var userId = document.getElementById("user").dataset.userId;



  // Set a new value

  document.getElementById("user").dataset.username = "new_username";

</script>

♿ Accessibility & Security

• Not a substitute for visible text — Important information for users should still appear in content or ARIA, not only in data-* attributes.
• Screen readers ignore data-* — They do not announce custom data attributes by default.
• No secrets — Never store passwords, tokens, or private data in data-*; users can see them in DevTools.
• Prefer semantic HTML — Use native elements and ARIA when conveying meaning to assistive tech.
• Validate parsed JSON — If you store JSON in data-*, wrap JSON.parse in try/catch.

💡 Best Practices

• Choose meaningful and descriptive names for your custom data-* attributes to maintain clarity in your code.
• Avoid storing sensitive or critical information in data-* attributes, as they are easily accessible through browser developer tools.
• Use the dataset property in JavaScript to interact with data-* attributes efficiently.