Custom Data Attributes

HTML allows you to add custom attributes to any element by prefixing them with data-. These are called data attributes and provide a standard way to embed extra information in your markup.

<button data-action="delete" data-item-id="42">Delete</button>

Data attributes:

• Are completely ignored by the browser's rendering engine.
• Do not affect semantics or accessibility (unless read by JavaScript).
• Are valid HTML — the data-* pattern is part of the specification.
• Can store any string value.

Data attribute names must follow these rules:

1. Start with data-.
2. Contain only lowercase letters, numbers, hyphens, dots, colons, and underscores.
3. No uppercase letters.

Common naming patterns

Keep names descriptive but concise. Use hyphens to separate words: data-user-role, not data-userrole.

JavaScript provides the dataset property on every element to read and write data attributes. Hyphenated names are converted to camelCase:

<div id="user" data-user-name="Alice" data-role="admin" data-login-count="5"></div>

const el = document.getElementById('user');

// Read
console.log(el.dataset.userName);   // "Alice"
console.log(el.dataset.role);        // "admin"
console.log(el.dataset.loginCount);  // "5" (always a string)

// Write
el.dataset.status = 'online';  // adds data-status="online"

// Delete
delete el.dataset.role;  // removes data-role attribute

Note that dataset values are always strings. Parse them with parseInt(), JSON.parse(), etc. as needed.

Good use cases

• UI state management: data-active="true", data-tab="settings"
• JavaScript hooks: data-action="save" for event delegation
• CSS targeting: [data-theme="dark"] { ... }
• Filtering/sorting: data-price="29.99", data-category="books"

When NOT to use data attributes

• Accessibility information — Use ARIA attributes (aria-label, aria-expanded, etc.) instead.
• Styling hooks only — Prefer CSS classes. Data attributes should carry data, not just be styling hooks.
• Large amounts of data — For complex data, store it in JavaScript objects and reference elements by ID.
• Sensitive data — Data attributes are visible in the DOM. Never store passwords, tokens, or personal information.