HTML5 Custom Attributes

TLDR

• data-* attributes are an HTML5 standard used to store custom data without triggering validation warnings.
• JavaScript uses the dataset API for access, and attribute names are automatically converted to lower camel case.
• The jQuery data() method does not directly manipulate DOM attributes; instead, it stores data in jQuery.cache.
• dataset only supports string types, whereas jQuery data() automatically performs type conversion (e.g., numbers, JSON objects).
• When accessing custom attributes, it is recommended to choose based on the context: native dataset is recommended for modern development, while jQuery data() may be considered if handling complex data types or requiring legacy browser compatibility.

Introduction to HTML5 Custom Attributes

The HTML5 specification allows the use of attributes starting with data- to store custom information. These attributes are valid in HTML documents and will not cause validation tools to report errors.

• When to encounter this: When developers need to attach extra information to HTML elements without violating W3C specifications.

JavaScript dataset API

In JavaScript, in addition to using getAttribute(), browsers map data- attributes to the dataset property of the DOM object (of type DOMStringMap).

• When to encounter this: When you need to access custom data on HTML elements using native JavaScript.

Attribute Name Conversion Rules

dataset automatically converts attribute names from HTML to JavaScript property names:

1. Remove the data- prefix.
2. Remove all - from the remaining name.
3. Convert the letter following the - to uppercase (lower camel case).

For example: data-cloudy-wing in HTML must be accessed via {DOM object}.dataset.cloudyWing in JavaScript.

jQuery data() Method

The jQuery data() method works differently from the native dataset mechanism. It stores data in jQuery.cache rather than directly manipulating the DOM property.

• When to encounter this: When a project relies on jQuery and requires automatic data type conversion (e.g., automatically converting strings to numbers or JSON objects).

Core Differences and Notes

• Storage Mechanism: data() only reads the HTML data-* attribute during the initial access; subsequent accesses are performed against jQuery.cache.
• Type Conversion: data() automatically determines the data type. If the attribute value is a JSON string, note the formatting requirements:

  data-wing='{"name": "wing", "height": 177}'

  The JSON string must be wrapped in single quotes, and internal property names must use double quotes for data() to correctly parse it into an Object.
• Version Differences: Since jQuery 1.8, strings starting with numbers (e.g., 012.050) are treated as strings rather than numbers to preserve the original data.

WARNING

This advice is based on the jQuery era. In environments where modern frontend frameworks (such as Vue, React) are prevalent, it is recommended to prioritize the state management mechanisms provided by the framework rather than directly manipulating DOM data-* attributes.

Changelog

• 2024-03-09 Initial document creation.