Existe um padrão que vejo em bases de código por toda parte: desenvolvedores precisam anexar dados personalizados a um elemento do DOM, então codificam isso em nomes de classes (class="item item-42 status-active"), armazenam em inputs ocultos, ou adicionam um objeto JavaScript com chave por algum ID. Todas essas são gambiarras. Os atributos data-* são a ferramenta certa para o trabalho, e estão integrados diretamente ao HTML Living Standard.

O que são Atributos data-*

A especificação de atributos data-* permite anexar qualquer dado personalizado de chave-valor a qualquer elemento HTML. O nome deve começar com data-, seguido de pelo menos um caractere. O valor é sempre uma string.

html
<!-- data-* attributes: custom data right on the element -->
<button
  data-action="delete"
  data-item-id="284"
  data-item-name="Summer Newsletter"
  data-confirm="true"
>
  Delete
</button>

<li
  data-product-id="SKU-9921"
  data-price="29.99"
  data-in-stock="true"
  data-category="electronics"
>
  Wireless Keyboard
</li>

Eles não afetam a renderização de forma alguma. Não adicionam classes, estilos ou comportamento de layout. São puramente metadados, legíveis por JavaScript e CSS, ignorados pelo motor de renderização do navegador.

Convenções de Nomenclatura

Os nomes de atributos de dados são insensíveis a maiúsculas/minúsculas em HTML (a especificação os converte para minúsculas), e eles mapeiam para camelCase na API dataset do JavaScript. A conversão é automática:

html
<!-- HTML attribute names use kebab-case -->
<div
  data-user-id="42"
  data-first-name="Alice"
  data-account-type="premium"
  data-last-login-at="2026-04-16T09:00:00Z"
>
</div>
js
// JavaScript dataset uses camelCase (automatic conversion)
const el = document.querySelector('div');

el.dataset.userId;       // "42"       (from data-user-id)
el.dataset.firstName;    // "Alice"    (from data-first-name)
el.dataset.accountType;  // "premium"  (from data-account-type)
el.dataset.lastLoginAt;  // "2026-04-16T09:00:00Z" (from data-last-login-at)

A regra: hífens em HTML viram camelCase em JavaScript. data-item-count → dataset.itemCount. Essa conversão é bidirecional — escrever em dataset.itemCount atualiza data-item-count no DOM.

Leitura e Escrita com dataset

A propriedade dataset é um DOMStringMap — se comporta como um objeto JavaScript comum para leitura e escrita, e o DOM é atualizado em tempo real:

js
const card = document.querySelector('.product-card');

// Reading
const productId  = card.dataset.productId;  // "SKU-9921"
const price      = parseFloat(card.dataset.price); // 29.99 (remember: always a string, parse as needed)
const inStock    = card.dataset.inStock === 'true'; // convert string to boolean

// Writing (updates the DOM attribute in real time)
card.dataset.price   = '24.99';       // sets data-price="24.99"
card.dataset.inStock = 'false';       // sets data-in-stock="false"
card.dataset.badgeText = 'Sale';      // adds data-badge-text="Sale" (new attribute)

// Deleting
delete card.dataset.badgeText;        // removes data-badge-text from the element

// Checking existence
if ('productId' in card.dataset) {
  console.log('This is a product card');
}
Lembre-se: Todos os valores de data-* são strings em HTML. Sempre converta números com parseInt() ou parseFloat(), e booleanos comparando com a string 'true'. Tratá-los como seu tipo original sem conversão é uma fonte comum de bugs.

Delegação de Eventos com Atributos data-*

Um dos usos mais práticos dos atributos de dados: delegação de eventos. Em vez de anexar listeners de evento individuais a dezenas de botões, anexe um único listener a um pai e leia a ação do dataset do elemento:

html
<ul id="task-list">
  <li data-task-id="101" data-status="pending">
    Write article draft
    <button data-action="complete" data-task-id="101">Complete</button>
    <button data-action="delete"   data-task-id="101">Delete</button>
  </li>
  <li data-task-id="102" data-status="pending">
    Review pull request
    <button data-action="complete" data-task-id="102">Complete</button>
    <button data-action="delete"   data-task-id="102">Delete</button>
  </li>
</ul>
js
const taskList = document.getElementById('task-list');

// One listener handles all buttons — even ones added dynamically later
taskList.addEventListener('click', (event) => {
  const button = event.target.closest('button[data-action]');
  if (!button) return; // click was somewhere else in the list

  const action = button.dataset.action;
  const taskId = button.dataset.taskId;

  switch (action) {
    case 'complete':
      markTaskComplete(taskId);
      break;
    case 'delete':
      deleteTask(taskId);
      break;
  }
});

function markTaskComplete(id) {
  const item = taskList.querySelector(`li[data-task-id="${id}"]`);
  item.dataset.status = 'complete'; // CSS can react to this change
  console.log(`Task ${id} marked complete`);
}

function deleteTask(id) {
  const item = taskList.querySelector(`li[data-task-id="${id}"]`);
  item.remove();
  console.log(`Task ${id} deleted`);
}

Este padrão escala para qualquer número de itens. event.target.closest() percorre o DOM a partir do elemento clicado para encontrar o ancestral mais próximo correspondente — então clicar no texto do botão (um nó de texto filho) ainda encontra o botão. É mais limpo do que comparar event.target.tagName e mais confiável do que verificar correspondências exatas de elementos.

Usando data-* com CSS attr()

O CSS pode ler valores de atributos de dados usando a função attr() em declarações content. Isso é útil para tooltips, badges e rótulos que vêm de dados em vez de marcação:

html
<!-- Tooltip text from data attribute -->
<span class="tooltip" data-tip="Saves automatically every 30 seconds">
  Auto-save enabled
</span>

<!-- Status badge text from data attribute -->
<li class="task" data-status="in-progress">Review PR #412</li>
<li class="task" data-status="complete">Write unit tests</li>
css
/* Tooltip using attr() in CSS */
.tooltip {
  position: relative;
  cursor: help;
  text-decoration: underline dotted;
}

.tooltip::after {
  content: attr(data-tip);
  position: absolute;
  bottom: 100%;
  left: 0;
  background: #1a1a2e;
  color: white;
  padding: 4px 8px;
  border-radius: 4px;
  font-size: 0.85rem;
  white-space: nowrap;
  opacity: 0;
  pointer-events: none;
  transition: opacity 0.2s;
}

.tooltip:hover::after,
.tooltip:focus::after {
  opacity: 1;
}

/* Status badge via attr() */
.task::before {
  content: '[' attr(data-status) '] ';
  font-size: 0.75rem;
  font-weight: bold;
  text-transform: uppercase;
}

.task[data-status="complete"] { text-decoration: line-through; color: #6b7280; }
.task[data-status="in-progress"] { color: #d97706; }

Note que attr() atualmente só funciona em propriedades content — você ainda não pode usá-lo para width, color ou outras propriedades CSS (embora a especificação CSS Values Level 5 esteja trabalhando para expandir isso). Por enquanto, seletores de atributo ([data-status="complete"]) são a forma prática de variar estilos com base em valores de atributos de dados.

Um Exemplo Interativo Completo — Acordeão com data-*

Aqui está um componente de acordeão do mundo real totalmente conduzido por atributos de dados para estado. Sem alternância de classes para comportamento, apenas atributos de dados — as classes permanecem apenas para estilização:

html
<div id="faq-accordion" role="list">
  <div class="accordion-item" role="listitem" data-open="false">
    <button
      class="accordion-trigger"
      data-target="faq-1"
      aria-expanded="false"
      aria-controls="faq-1"
    >
      What is the difference between article and section?
    </button>
    <div id="faq-1" class="accordion-panel" data-panel hidden>
      <p>An <code>article</code> is self-contained content that could stand alone.
      A <code>section</code> is a thematic grouping within a larger context.</p>
    </div>
  </div>

  <div class="accordion-item" role="listitem" data-open="false">
    <button
      class="accordion-trigger"
      data-target="faq-2"
      aria-expanded="false"
      aria-controls="faq-2"
    >
      When should I use ARIA roles?
    </button>
    <div id="faq-2" class="accordion-panel" data-panel hidden>
      <p>Only when no native HTML element conveys the same semantics.
      Native elements should always be preferred.</p>
    </div>
  </div>
</div>
js
const accordion = document.getElementById('faq-accordion');

accordion.addEventListener('click', (event) => {
  const trigger = event.target.closest('.accordion-trigger');
  if (!trigger) return;

  const targetId = trigger.dataset.target;
  const panel    = document.getElementById(targetId);
  const item     = trigger.closest('.accordion-item');
  const isOpen   = item.dataset.open === 'true';

  // Toggle this item
  item.dataset.open       = isOpen ? 'false' : 'true';
  trigger.ariaExpanded    = isOpen ? 'false' : 'true';
  panel.hidden            = isOpen;
});
css
.accordion-trigger {
  width: 100%;
  text-align: left;
  background: none;
  border: none;
  padding: 1rem;
  font-size: 1rem;
  cursor: pointer;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

/* Arrow rotates based on data-open state */
.accordion-item[data-open="false"] .accordion-trigger::after {
  content: '▼';
  transition: transform 0.2s;
}

.accordion-item[data-open="true"] .accordion-trigger::after {
  content: '▲';
}

.accordion-panel {
  padding: 0 1rem 1rem;
}

.accordion-panel[hidden] {
  display: none;
}

O estado fica em data-open no contêiner. O CSS lê esse atributo para girar o indicador de seta. O JavaScript alterna o atributo e gerencia aria-expanded e hidden. Cada camada faz exatamente um trabalho, e elas se compõem de forma limpa.

Notas sobre Performance e Acessibilidade

  • Performance. Atributos data-* fazem parte do DOM e lê-los é muito rápido — essencialmente o mesmo que ler qualquer outro atributo. Para caminhos de código extremamente frequentes (milhares de leituras por frame), um JavaScript Map com chave por referência de elemento é mais rápido. Mas para código de UI típico, dataset é suficiente.
  • data-* é para scripts, não para semântica. Esses atributos são invisíveis para leitores de tela, a menos que você os vincule explicitamente a estados ARIA. Não use data-role ou data-label para transmitir semântica — use elementos HTML adequados e atributos WAI-ARIA para isso.
  • Segurança. Nunca coloque dados sensíveis (tokens, senhas, dados pessoais) em atributos de dados. Eles são visíveis no inspetor de elementos do navegador e legíveis por qualquer JavaScript na página, incluindo scripts de terceiros.
  • Consultas. Você pode selecionar elementos por atributo de dados com seletores de atributo CSS: document.querySelectorAll('[data-action="delete"]') — isso funciona exatamente como esperado e é muito útil para operações em massa.

Ferramentas para Desenvolvimento HTML

Ao trabalhar com HTML, o Formatador HTML mantém sua marcação cheia de atributos legível, e o Validador HTML detecta erros como IDs duplicados que podem quebrar associações aria-controls. Para edição ao vivo e visualização de padrões de componentes como o acordeão acima, o Editor HTML permite ver as alterações em tempo real sem uma etapa de build.

Conclusão

Os atributos de dados são a forma limpa e oficial de anexar metadados personalizados a elementos do DOM. Eles superam hacks de nome de classe, inputs ocultos e mapas JavaScript externos para a maioria dos casos de uso. A API dataset torna a leitura e escrita simples, a conversão camelCase é automática, e eles se compõem naturalmente com seletores de atributo CSS e padrões de delegação de eventos. Lembre-se apenas: atributos de dados são para metadados legíveis por scripts, não para semântica de acessibilidade — isso é função do ARIA.

← All HTML articles Browse all categories →