path: root/devdocs/html/global_attributes%2Fdata-%2A.html

<header><h1>data-*</h1></header><div class="section-content"><p>The <code>data-*</code> <a href="../global_attributes">global attributes</a> form a class of attributes called <strong>custom data attributes</strong>, that allow proprietary information to be exchanged between the <a href="../index">HTML</a> and its <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model">DOM</a> representation by scripts.</p></div>
<h2 id="try_it">Try it</h2>
<div class="section-content">
<iframe class="interactive is-tabbed-standard-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/attribute-data.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe> <p> All such custom data are available via the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement"><code>HTMLElement</code></a> interface of the element the attribute is set on. The <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset"><code>HTMLElement.dataset</code></a> property gives access to them. The <code>*</code> may be replaced by any name following <a href="https://www.w3.org/TR/REC-xml/#NT-Name" target="_blank">the production rule of XML names</a> which includes the following recommendations: </p> <ul> <li>The name should not start with <code>xml</code> (case-insensitive), as it's reserved for future XML specifications.</li> <li>The name should not contain any colon characters (<code>:</code>), as XML assigns meaning to such names.</li> <li>The name should not contain any capital letters, as XML is all lowercase.</li> </ul> <p>These are recommendations. If these naming recommendations are not followed, no errors will occur. The attributes will still be matched using CSS <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors">attribute selectors</a>, with the attribute being case insensitive and any attribute value being case-sensitive. Attributes not conforming to these three recommendations will also still be recognized by the JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset"><code>HTMLElement.dataset</code></a> property and user-agents will include the attribute in the <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMStringMap"><code>DOMStringMap</code></a> containing all the custom data attributes for an <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement"><code>HTMLElement</code></a>.</p> <p>If you plan to use <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset"><code>HTMLElement.dataset</code></a>, the portion of the attribute name following the <code>data-</code> can only include characters allowed in JavaScript property names (and hyphens, which will be removed). The <code>dataset</code> version of the attribute name removes the "data-" prefix and converts the rest of the name from <a href="https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case">kebab-case</a> to camelCase. For example, <code>element.getAttribute("data-test")</code> is equivalent to <code>element.dataset.test</code> and <code>data-test-abc</code> will be accessible as <code>HTMLElement.dataset.testAbc</code> (or by <code>HTMLElement.dataset["testAbc"]</code>). Avoid non-alphabetic characters following a hyphen, such as <code>data-test-1</code> or <code>data--test</code>, as they will not be recognized by <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset"><code>HTMLElement.dataset</code></a>.</p>
</div>
<h3 id="usage">Usage</h3>
<div class="section-content">
<p>By adding <code>data-*</code> attributes, even ordinary HTML elements can become rather complex and powerful program-objects. For example, a space-ship "<a href="https://en.wikipedia.org/wiki/Sprite_(computer_graphics)" target="_blank">sprite</a><em>"</em> in a game could be a simple <a href="../element/img"><code>&lt;img&gt;</code></a> element with a <a href="class"><code>class</code></a> attribute and several <code>data-*</code> attributes:</p> <div class="code-example">
<p class="example-header"><span class="language-name">html</span></p>
<pre data-signature="a1qPQkSymHZrc1ikVb3riZH1wdTVj2cS0/1v256K3Bg=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>img</span>
  <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>spaceship cruiserX3<span class="token punctuation">"</span></span>
  <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>shipX3.png<span class="token punctuation">"</span></span>
  <span class="token attr-name">data-ship-id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>324<span class="token punctuation">"</span></span>
  <span class="token attr-name">data-weapons</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>laserI laserII<span class="token punctuation">"</span></span>
  <span class="token attr-name">data-shields</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>72%<span class="token punctuation">"</span></span>
  <span class="token attr-name">data-x</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>414354<span class="token punctuation">"</span></span>
  <span class="token attr-name">data-y</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>85160<span class="token punctuation">"</span></span>
  <span class="token attr-name">data-z</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>31940<span class="token punctuation">"</span></span>
  <span class="token special-attr"><span class="token attr-name">onclick</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span><span class="token value javascript language-javascript">spaceships<span class="token punctuation">[</span><span class="token keyword">this</span><span class="token punctuation">.</span>dataset<span class="token punctuation">.</span>shipId<span class="token punctuation">]</span><span class="token punctuation">.</span><span class="token function">blasted</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span><span class="token punctuation">"</span></span></span> <span class="token punctuation">/&gt;</span></span>
</pre>
</div> <p>For a more in-depth tutorial about using HTML data attributes, see <a href="https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes">Using data attributes</a>.</p>
</div>
<h2 id="specifications">Specifications</h2>
<div class="_table"><table class="standard-table">
<thead><tr><th scope="col">Specification</th></tr></thead>
<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/dom.html#attr-data-*">HTML Standard <br><small># attr-data-*</small></a></td></tr></tbody>
</table></div>
<h2 id="browser_compatibility">Browser compatibility</h2>
<div class="_table"><table>
<thead>
<tr id="bct-browser-type">
<th></th>
<th colspan="6">Desktop</th>
<th colspan="6">Mobile</th>
</tr>
<tr id="bct-browsers">
<th></th>
<th>Chrome</th>
<th>Edge</th>
<th>Firefox</th>
<th>Internet Explorer</th>
<th>Opera</th>
<th>Safari</th>
<th>WebView Android</th>
<th>Chrome Android</th>
<th>Firefox for Android</th>
<th>Opera Android</th>
<th>Safari on IOS</th>
<th>Samsung Internet</th>
</tr>
</thead>
<tbody><tr>
<th><code>data-*</code></th>
<td class="bc-supports-yes">7</td>
<td class="bc-supports-yes">12</td>
<td class="bc-supports-yes">6</td>
<td class="bc-supports-yes">Yes</td>
<td class="bc-supports-yes">15</td>
<td class="bc-supports-yes">5.1</td>
<td class="bc-supports-yes">4.4</td>
<td class="bc-supports-yes">18</td>
<td class="bc-supports-yes">6</td>
<td class="bc-supports-yes">14</td>
<td class="bc-supports-yes">5</td>
<td class="bc-supports-yes">1.0</td>
</tr></tbody>
</table></div>
<h2 id="see_also">See also</h2>
<div class="section-content"><ul> <li>All <a href="../global_attributes">global attributes</a>.</li> <li>The <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset"><code>HTMLElement.dataset</code></a> property that allows to access and modify these values.</li> <li><a href="https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes">Using data attributes</a></li> </ul></div><div class="_attribution">
  <p class="_attribution-p">
    &copy; 2005&ndash;2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br>
    <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*</a>
  </p>
</div>