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 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

Compatibilidad en navegadores

BCD tables only load in the browser

Ver también