HTMLElement.dataset — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLElement.dataset

Beschreibung

Die Eigenschaft dataset gibt ein DOMStringMap-Objekt zurück. Darin steht jedes benutzerdefinierte Datenattribut (data-*) des Elements als eigene Eigenschaft. Die Eigenschaft dataset selbst ist schreibgeschützt, man kann ihr also kein neues Objekt zuweisen. Die einzelnen Einträge kann man aber lesen, ändern, neu anlegen und mit delete entfernen. Jede Änderung wird sofort als Attribut ins DOM übernommen.

Attributnamen werden automatisch umgewandelt: Aus data-user-id in HTML wird dataset.userId in JavaScript. Das Präfix data- fällt weg, und jeder Bindestrich mit folgendem Kleinbuchstaben wird zu einem Großbuchstaben (camelCase). In der Gegenrichtung wird aus dataset.sortOrder = "asc" das Attribut data-sort-order="asc".

Typische Einsatzfälle sind Konfigurationswerte für Komponenten, IDs für Event-Delegation, Zustände für CSS-Selektoren (z. B. [data-state="open"]) und das Weitergeben von Server-Daten an clientseitige Skripte, ohne versteckte Felder oder globale Variablen zu brauchen.

Alle Werte sind immer Zeichenketten. Zahlen, Wahrheitswerte oder Objekte muss man beim Schreiben selbst umwandeln (z. B. mit JSON.stringify) und beim Lesen wieder zurückwandeln (Number(), JSON.parse()).

Rückgabewert

Typ

DOMStringMap

Beschreibung

Ein Live-Objekt mit allen data-*-Attributen des Elements in camelCase-Schreibweise. Die Werte sind immer vom Typ string. Fragt man ein Attribut ab, das es nicht gibt, erhält man undefined.

Beispiele

Datenattribute lesen, setzen und löschen

// <div id="user" data-user-id="42" data-role="admin"></div>
const el = document.getElementById('user');

console.log(el.dataset.userId);   // "42"
console.log(el.dataset.role);     // "admin"

el.dataset.lastLogin = '2024-05-01'; // erzeugt data-last-login
delete el.dataset.role;              // entfernt data-role

console.log(el.outerHTML);

42 admin <div id="user" data-user-id="42" data-last-login="2024-05-01"></div>

Event-Delegation mit data-Attributen

// <ul id="list">
//   <li data-product-id="101" data-price="19.90">Buch</li>
//   <li data-product-id="102" data-price="4.50">Stift</li>
// </ul>
const list = document.getElementById('list');

list.addEventListener('click', (event) => {
  const item = event.target.closest('[data-product-id]');
  if (!item) return;

  const { productId, price } = item.dataset;
  const priceNum = Number(price); // Werte sind immer Strings!
  console.log(`Produkt ${productId} kostet ${priceNum.toFixed(2)} €`);
});

Produkt 101 kostet 19.90 € (nach Klick auf „Buch“)

Komplexe Daten als JSON speichern und Zustand für CSS setzen

const panel = document.querySelector('.panel');

// Objekt serialisieren
panel.dataset.config = JSON.stringify({ autoClose: true, delay: 3000 });
const config = JSON.parse(panel.dataset.config);
console.log(config.delay);

// Zustand umschalten, CSS reagiert auf .panel[data-state="open"]
const toggle = () => {
  panel.dataset.state = panel.dataset.state === 'open' ? 'closed' : 'open';
};
toggle();
console.log(panel.dataset.state);

// Alle Einträge durchlaufen
for (const [key, value] of Object.entries(panel.dataset)) {
  console.log(key, '=>', value);
}

3000 open config => {"autoClose":true,"delay":3000} state => open

// Wichtig · Fallstricke

Nur Zeichenketten: el.dataset.count = 5 speichert "5". Mit el.dataset.active = false wird die Zeichenkette "false" gespeichert, und die ist in einer Bedingung truthy. Werte also immer ausdrücklich umwandeln.
Namensumwandlung: Bindestriche und Großbuchstaben passen nicht immer 1:1 zusammen. data-fooBar in HTML wird zu data-foobar (HTML-Attribute sind nicht case-sensitiv) und ist daher als dataset.foobar erreichbar. Wer in JavaScript einen Namen mit Bindestrich setzt, auf den ein Kleinbuchstabe folgt, etwa dataset['a-b'], bekommt einen SyntaxError.
Nicht zuweisbar: el.dataset = {} hat keine Wirkung (im Strict Mode gibt es einen TypeError). Einträge darum einzeln setzen oder Object.assign(el.dataset, {...}) verwenden.
Sicherheit: Datenattribute sind im DOM für jeden sichtbar und lassen sich manipulieren. Keine Geheimnisse (Tokens, Passwörter) darin ablegen und Werte vor der Verwendung prüfen. Werte, die in innerHTML landen, müssen maskiert werden, sonst droht XSS.
Performance: Für große Datenmengen oder häufig wechselnde Daten sind WeakMap oder JavaScript-Eigenschaften besser geeignet, weil jeder Schreibzugriff das DOM verändert und MutationObserver auslöst.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch von SVGElement und MathMLElement. Nur sehr alte Browser (IE ≤ 10) brauchen stattdessen getAttribute('data-…').

Siehe auch

Element.getAttribute() Element.setAttribute() Element.removeAttribute() DOMStringMap HTMLElement Element.closest() HTMLElement.translate