HTMLElement.dataset

La propiedad dataset en HTMLElement proporciona una interfaz lectura/escritura para obtener todos los atributos de datos personalizados (data-*) de cada uno de los elementos. Est谩 disponible el acceso en HTML y en el DOM.  Dentro del map of DOMString, aparece una entrada por cada atributo de datos. Hay que tener en cuenta que la propiedad dataset puede leerse, pero no modificarse directamente.  En vez de eso, las escrituras deben ser realizadas a trav茅s de cada propiedad individual del dataset, que representan a cada atributo correspondiente. Adem谩s un HTML data-attribute y su correspondiente DOM dataset.property no comparten el mismo nombre, pero son siempre similares:

  • El nombre de un attributo de datos comienza en HTML con data-. S贸lo puede estar formado por letras min煤sculas, n煤meros y los caracteres: gui贸n (-), punto (.), dos puntos (:) y gui贸n bajo (_) -- NUNCA una letra may煤scula (A a Z).
  • El nombre del atributo en JavaScript ser谩 el del correspondiente atributo HTML pero en camelCase, sin guiones, puntos, etc.

Adicionalmente, encontrar谩s una gu铆a de como usar los atributos data de HTML en nuestro articulo Using data attributes.

Conversion de nombres

dash-style a camelCase: Un atributo de datos personalizado se transforma en una clave para la entrada DOMStringMap (en-US) con las siguientes reglas

  • el prefijo data- es eliminado (incluyendo el gui贸n);
  • por cada gui贸n (U+002D) seguido de un caracter ASCII que sea una letra en minuscula a a la z, el gui贸n es removido y la letra se transforma en su contraparte en mayuscula;
  • otros caracteres (incluyendo otros guines) se mantienen intactos.

camelCasedash-style: La conversi贸n opuesta, mapea una clave en un nombre de atributo, usa las siguientes reglas:

  • Restricci贸n: Un gui贸n no debe ser inmediatamente seguido por un un caracter ASCII que sea una letra minuscula de la a a la z (antes de la conversi贸n);
  • se agrega el prefijo data-;
  • cualquier caracter ASCII que sea una letra mayuscula de la A a la Z se convierte en un gui贸n seguido de se contraparte en minuscula;
  • otros caracteres se mantienen intactos.

La restricci贸n en las reglas anteriores aseguran que las dos conversiones sean inversas una a la otra.

Por ejemplo, el atributo nombrado data-abc-def corresponde a la clave abcDef.

Accediendo valores

  • Los atributos pueden ser definidos y obtenidos usando el nombre camelCase (la clave) como la propiedad de un objeto del dataset, como en element.dataset.keyname
  • Los atributos tambien pueden ser definidos y obtenidos usando la sintaxis de corchetes, como en element.dataset[keyname]
  • El operador in puede ser usado para checar si un atributo dado existe.

Definiendo valores

  • Cuando un atributo es definido, su valor siempre se convierte a string. Por ejemplo, null siempre se convierte en el string "null".
  • Cuando quieras remover un atributo, puedes usar el operador delete.

Sintaxis

  • string = element.dataset.camelCasedName;
  • element.dataset.camelCasedName = string;

  • string = element.dataset[camelCasedName];
  • element.dataset[camelCasedName] = string;

  • Custom data attributes can also be set directly on HTML elements, but attribute names must use the data- syntax above.

Ejemplos

<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe</div>
const el = document.querySelector('#user');

// el.id == 'user'
// el.dataset.id === '1234567890'
// el.dataset.user === 'johndoe'
// el.dataset.dateOfBirth === ''

// set the data attribute
el.dataset.dateOfBirth = '1960-10-03';
// Result: el.dataset.dateOfBirth === 1960-10-03

delete el.dataset.dateOfBirth;
// Result: el.dataset.dateOfBirth === undefined

// 'someDataAttr' in el.dataset === false
el.dataset.someDataAttr = 'mydata';
// Result: 'someDataAttr' in el.dataset === true

Especificaciones

Especificaci贸n Estado Comentario
HTML Living Standard
La definici贸n de 'HTMLElement.dataset' en esta especificaci贸n.
Living Standard No change from latest snapshot, HTML 5.1
HTML 5.1
La definici贸n de 'HTMLElement.dataset' en esta especificaci贸n.
Recommendation Snapshot of HTML Living Standard, no change from HTML5
HTML5
La definici贸n de 'HTMLElement.dataset' en esta especificaci贸n.
Recommendation Snapshot of  HTML Living Standard, initial definition.

Compatibilidad en navegadores

BCD tables only load in the browser

Ver tambi茅n