0Pricing
HTML Academy · Lesson

data-* Syntax and Naming Conventions

Understand valid data-* attribute names and their purpose.

data-* Syntax and Naming Conventions is a free HTML Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the HTML Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Review: data-* Attributes

Data attributes (data-*) store custom information on HTML elements:

<div data-user-id="42" data-role="admin" data-active="true">
  User Card
</div>

Valid Naming Rules

data-* attribute naming requirements:

  • Must start with data-
  • Followed by at least one character
  • Only lowercase letters, digits, hyphens, underscores, periods, colons
  • No uppercase letters (HTML parser lowercases attributes)
  • No spaces

Naming Conventions

Community naming conventions:

<!-- BEM-style: module__element--modifier -->
data-card="profile"
data-card-id="42"
data-card-state="expanded"

<!-- Descriptive: domain-concept -->
data-product-id="SKU-123"
data-analytics-event="click-cta"
data-feature-flag="dark-mode"

Multiple Data Attributes

An element can have any number of data attributes:

<button
  type="button"
  data-action="delete"
  data-target-id="user-42"
  data-confirm="true"
  data-confirm-message="Delete this user permanently?"
>Delete</button>

Values Are Always Strings

Data attribute values are always strings — parse them in JavaScript:

const el = document.querySelector('[data-user-id]');

console.log(el.dataset.userId);              // '42' (string)
console.log(typeof el.dataset.userId);       // 'string'

// Parse to number:
const id = parseInt(el.dataset.userId, 10);   // 42 (number)

// Parse to boolean:
const active = el.dataset.active === 'true'; // true (boolean)

// Parse to JSON:
const config = JSON.parse(el.dataset.config); // object

Storing JSON in data-*

Store complex data as JSON strings:

<div
  data-config='{"theme":"dark","locale":"en-US","pageSize":20}'
  id="app"
></div>

<script>
const el = document.getElementById('app');
const config = JSON.parse(el.dataset.config);
console.log(config.theme);    // 'dark'
console.log(config.pageSize); // 20
</script>

data-* vs Custom Elements

When to choose data-* vs custom elements vs JavaScript objects:

  • data-* — element-specific metadata, visible in HTML, accessible from CSS
  • Custom elements — complex reusable components with encapsulated behavior
  • JavaScript Map/WeakMap — data not needed in HTML; large or complex data

Framework data-* Usage

Common framework uses of data attributes:

<!-- Bootstrap: target collapsible elements -->
<button data-bs-toggle="collapse" data-bs-target="#menu">
  Toggle
</button>

<!-- Alpine.js: component data -->
<div x-data="{ open: false }">

<!-- Stimulus: controller identification -->
<div data-controller="menu" data-menu-open-value="false">

<!-- Testing libraries: stable selectors -->
<button data-testid="submit-btn">Submit</button>

Accessibility and data-*

Data attributes are not announced by screen readers — don't use them for accessibility information:

<!-- BAD: accessibility info in data-* -->
<button data-label="Close dialog">×</button>
<!-- Screen reader does NOT read data-label -->

<!-- GOOD: use aria-label for accessibility -->
<button aria-label="Close dialog">×</button>

Performance Considerations

data-* attributes have negligible performance impact:

  • Reading dataset is fast (O(1))
  • Heavy use of data-* on thousands of elements is fine
  • Storing large blobs (images, large JSON) in data-* is wasteful
  • Use WeakMap to store large JS objects associated with DOM elements

Summary: data-* Best Practices

data-* best practices:

  • Use lowercase, hyphenated names
  • Values are always strings — parse as needed
  • For JSON: JSON.stringify / JSON.parse
  • Use for metadata that CSS or JavaScript needs
  • Not a replacement for ARIA attributes
  • Don't store secrets (visible in DevTools)

Quick Check

What type does dataset always return attribute values as?

Recap: data-* Syntax

data-* naming essentials:

  • Format: data-[lowercase-name]="value"
  • Accessed as: element.dataset.camelCaseName
  • All values are strings — parse explicitly
  • Store JSON for complex data
  • Lowercase, no uppercase, no spaces in attribute name

Frequently asked questions

Is the “data-* Syntax and Naming Conventions” lesson free?

Yes — the full text of “data-* Syntax and Naming Conventions” is free to read here on the web, and the HTML Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the HTML Academy course, upgrade to CoddyKit PRO.

What will I learn in “data-* Syntax and Naming Conventions”?

Understand valid data-* attribute names and their purpose. You practise HTML Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start HTML Academy?

No prior experience is required. HTML Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “data-* Syntax and Naming Conventions” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this HTML Academy lesson?

Yes. Every HTML Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. data-* Syntax and Naming Conventions
  2. Accessing data-* with dataset in JavaScript
  3. Using data-* with CSS attribute selectors
  4. Real-world Patterns Tooltips State Tracking
← Back to HTML Academy