HTML data-* Attribute

The data-* attribute attaches additional data to an element. This data is not visible to the user, but is commonly used by JavaScript to improve a site‘s user experience.

Example

#

Three list items (fruits) with custom data-id and data-price data attached.

  • Bananas
  • Oranges
  • Apples
<ul>
  <li data-id="205" data-price="$1.55">Bananas</li>
  <li data-id="312" data-price="$2.99">Oranges</li>
  <li data-id="315" data-price="$1.97">Apples</li>
</ul>

Note:   data-* attributes are not visible to the users.


Using data-*

The data-* attribute adds custom values to an HTML element.

The * part is replaced with a lowercase string, such as data-id, data-cost, or data-location..

An element can have any number of data-* attributes, each with their own name.

These attributes store additional data about an element (e.g. id, sell-by-date, variation, etc.).

The data is commonly used by JavaScript to improve a site's user-experience.

Tip:  data-* attributes are global attributes that can be applied to any HTML element.

Tip: Although users cannot see the data-* attributes, their values are present in the document.
For this reason, do not include sensitive data values.


Syntax

<tag data-*="value" />

Values

#

Value Description
* A lower-case string that is at least 1 character long, such as id, parent, cost, status, etc.
value String that represents the value of the custom data attribute. Can be any alphanumeric string, including JSON or HTML.

More Examples

Four <a> tags with custom data-country attributes.
Clicking a city will display its country.

<nav>
  <a data-country="Netherlands" onclick="show(this);" href="#null">Amsterdam</a> <br />
  <a data-country="Belgium" onclick="show(this);" href="#null">Brussels</a> <br />
  <a data-country="France" onclick="show(this);" href="#null">Paris</a> <br />
  <a data-country="Spain" onclick="show(this);" href="#null">Madrid</a> <br />
</nav>

<script>
  let show = element => {
       alert("Country = " + element.getAttribute('data-country'));
  }
</script>

Code explanation

Four links are created with <a> tags.

Each has a custom data-country attribute with a country name.

Mouse clicks are handled by the onclick event.

Onclick invokes a JavaScript function that extracts and displays the country.


Accessing data-* attributes with JavaScript

JavaScript can access data-* attribute values in two ways:

  1. with the getAttribute() method
  2. with the dataset property (which is a DOMStringMap)

In the example below, clicking the first two links invokes the getAttribute() method.
And clicking the last two links uses the simpler dataset property.

<nav>
  1. <a data-country="Netherlands" onclick="show1(this)" href="#null">Amsterdam</a> <br />
  1. <a data-country="Belgium" onclick="show1(this)" href="#null">Brussels</a> <br />
  2. <a data-country="France" onclick="show2(this)" href="#null">Paris</a> <br />
  2. <a data-country="Spain" onclick="show2(this)" href="#null">Madrid</a> <br />
</nav>

<script>
  let show1 = element => {
       alert("Country = " + element.getAttribute('data-country'));
  }

  let show2 = element => {
       alert("Country = " + element.dataset.country);
  }
</script>

When accessing a dataset you drop the data- prefix.
In the above example, the attribute is data-country and the property is country.

Property names on a dataset are camelCased without the dashes.
For example, data-country-of-origin is queried as dataset.countryOfOrigin.


Did you know?

Did you know?

The data-* attribute accepts any string value

The data-* attribute accepts strings, numbers, boolean, decimals -- all treated as string values.

The data-* attribute also accepts JSON as long as quotes and special characters are correctly handled.

The code below shows how JSON can be used as a data-* attribute value.

<ul>
  <li data-product='
    {
      "id": 145,
      "sku": "PA439-B",
      "price": 4.66
    }
  '>Oma's Chocolate Chip Cookies</li>
</ul>

Elements using the data-* attribute

The data-* attribute is a global attribute that can be applied to any element.
Click on any tag for an example of that element using an data-* attribute.

Tag with data-* Description
<a> Creates a link (hyperlink) to another page
<article> Defines a container for independent and self contained text
<aside> Creates a content area that is related to the primary content on a page
<audio> Creates a player for sound such as music, sound effects, or others
<blockquote> Defines a section with text quoted from another source
<body> Specifies a container for the page's content with text, links, images, etc.
<button> Creates a clickable button that can contain text or an image
<canvas> Creates a graphics container where JavaScript can draw.
<col> Specifies column properties for a table
<div> Creates a division or section on a page
<figure> Displays self-contained content, usually an image
<footer> Defines a footer section on a page or a section of a page
<form> Defines a data entry area that contains input elements
<header> Defines a header section on a page or a section of a page
<iframe> Creates a frame in which another web page can be embedded
<img> Creates an image
<input> Creates an input field in which data can be entered
<label> Creates a label or brief description before input elements
<li> Defines a list item. Used in <ol> and <ul> elements
<main> Specifies a container for the main content of the page
<meter> Creates a measurement control, like a guage
<nav> Creates a container for navigation links
<object> Embeds external objects in a page, such as, audio, video, image, or PDF
<ol> Creates a numerically or alphabetically ordered list
<optgroup> Groups related options in a <select> element (dropdown control)
<option> Adds an item to a <select> element (dropdown control)
<picture> Adds images with a bit more flexibility than the <img> element
<pre> Displays pre-formatted text in fixed-width font -- usually computer code
<progress> Creates a control that displays progress of a task
<section> Defines a piece of content that can stand on its own
<select> Creates a dropdown control
<span> Container for one or more inline text elements
<svg> Creates an vector image
<table> Creates an HTML table with rows and colums, much like a spreadsheet
<tbody> Marks the table body in an HTML table
<td> Creates an HTML table cell
<textarea> Creates a multi-line text input control, for example for messages
<tfoot> Marks the table footer in an HTML table
<th> Creates an HTML table header cell
<thead> Marks the header rows in an HTML table
<tr> Creates a table row with either <th> or <td> elements
<ul> Creates an unordered, bulleted list
<video> Creates a video player on a page

Browser support

Here is when data-* support started for each browser:

Chrome
4.0 Jan 2010
Firefox
2.0 Oct 2006
Edge
5.5 Jul 2000
Opera
9.6 Oct 2008
Safari
3.1 Mar 2008

You may also like



Guides