Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

HTMLElement.dataset — accéder aux attributs data-*

HTMLElement.dataset expose les attributs data-* d’un élément sous la forme d’une DOMStringMap. Il permet de lire, d’écrire et de supprimer des données textuelles, en associant par exemple data-user-id à userId.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

element.dataset.key
 element.dataset.key = value;
 element.dataset[key] = value;
 delete element.dataset.key;

HTMLElement.dataset renvoie une DOMStringMap associée à un élément, et non une copie indépendante des données. Les modifications des propriétés mettent à jour les attributs data-*, et inversement. La propriété dataset elle-même est en lecture seule ; ce sont ses propriétés que l’on modifie.

La correspondance des noms supprime le préfixe data- ; un trait d’union suivi d’une lettre minuscule ASCII est supprimé, et cette lettre devient majuscule : data-user-id → userId. Les autres caractères restent inchangés. Lors de l’écriture, les lettres majuscules ASCII deviennent un trait d’union suivi de la lettre minuscule correspondante. Écrire une clé contenant un trait d’union suivi d’une minuscule ASCII, comme dataset['user-id'], déclenche SyntaxError.

Les valeurs sont des chaînes : convertissez explicitement les nombres. Attribuer null enregistre le texte "null" au lieu de supprimer l’attribut. Utilisez delete element.dataset.userId pour le supprimer. Une clé userId absente renvoie undefined.

Il s’agit d’une interface du HTML Living Standard, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. Les moteurs de navigateur actuels la prennent en charge ; la présence de Node 24 dans un dépôt ne prouve pas que le DOM y est disponible.

Exemples

const element = document.createElement('div');
element.setAttribute('data-user-id', '42');
console.log(element.dataset.userId);
element.dataset.userId = Number(element.dataset.userId) + 1;
console.log(element.getAttribute('data-user-id'));
console.log(typeof element.dataset.userId);
delete element.dataset.userId;
console.log(element.hasAttribute('data-user-id'));

Résultat

42
43
string
false

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources