HTMLElement: dataset プロパティ

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

dataset は HTMLElement インターフェイスの読み取り専用プロパティで、要素に設定されたすべてのカスタムデータ属性 (data-*) への読み取り/書き込みアクセスを提供します。これは文字列のマップである (DOMStringMap) で、それぞれの data-* 属性の項目です。

メモ: dataset プロパティ自体は読み取ることができますが、直接書き込むことはできません。すべての書き込みは、個々の data 属性を表す dataset 内の個々のプロパティを表します。

また、 HTML の data-* 属性とそれに対応する DOM の dataset.プロパティ は同じ名前にはなりませんが、次のように常に近いものになります。

HTML では: 属性の名前は、 data- で始まります。文字、数字、ダッシュ (-)、ドット (.)、コロン (:)、アンダースコア (_) のみを入れることができます。ASCII 大文字の A から Z は小文字に変換されます。
JavaScript では: カスタムデータ属性のプロパティ名は、同じ HTML 属性の名前から data- の接頭辞を除いたものですが、そのプロパティのキャメルケースの名前であり、単一のダッシュ (-) を除いたものです。

以下の情報に加えて、データ属性の使用の記事に、HTML データ属性の使用方法に関するガイドがあります。

名前の変換

ダッシュスタイルからキャメルケースへの変換

カスタムデータ属性名は、次のルールに従って DOMStringMap 項目のキーに変換されます。

すべての ASCII の大文字 (A から Z まで) を小文字にします。
接頭辞の data- を（ダッシュを含め）削除します。
ダッシュ (U+002D) に ASCII 小文字の a から z が続く場合、ダッシュを削除し、その文字を対応する大文字に変換します。
他の文字 (他のダッシュを含む) は変更しません。

キャメルケースからダッシュスタイルへの変換

キーを属性名にマッピングする逆の変換では、以下のように次のルールが使用されます。

制約事項: 変換前に置いて、ダッシュの直後に ASCII 小文字 a から z を続けてはなりません。
接頭辞として data- が追加されます。
ASCII 大文字の A から Z は、ダッシュと、その後に対応する小文字が続くものに変換されます。
他の文字は変更しません。

例えば、data-abc-def という名前の属性は、キー abcDef に対応します。

値へのアクセス

属性は dataset のオブジェクトプロパティのようにキャメルケース名（キー）を使用して、 element.dataset.keyname のように設定したり読み取ったりすることができます。
属性はブラケット構文を使用して、 element.dataset['keyname'] のように設定したり読み取ったりすることもできます。
in 演算子を 'keyname' in element.dataset のように使用すると、特定の属性が存在するかどうかを確認できます。これは dataset のプロトタイプチェーンを走査することになり、プロトタイプチェーンを汚染する可能性のある外部コードを持っている場合には安全ではないことに注意してください。例えば Object.hasOwn(element.dataset, 'keyname') や、単に element.dataset.keyname !== undefined かどうかを調べる方法などがあります。

値の設定

属性が設定されると、その値は常に文字列に変換されます。例えば、 element.dataset.example = null は data-example="null" に変換されます。
属性を削除する場合は、delete 演算子が使用できます。

値

DOMStringMap です。

例

html

<div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth>
  Carina Anand
</div>

const el = document.querySelector("#user");

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

// データ属性の設定
el.dataset.dateOfBirth = "1960-10-03";
// JS での結果: el.dataset.dateOfBirth === '1960-10-03'
// HTML での結果: <div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth="1960-10-03">Carina Anand</div>

delete el.dataset.dateOfBirth;
// JS での結果: el.dataset.dateOfBirth === undefined
// HTML での結果: <div id="user" data-id="1234567890" data-user="carinaanand">Carina Anand</div>

if (el.dataset.someDataAttr === undefined) {
  el.dataset.someDataAttr = "mydata";
  // JS での結果: 'someDataAttr' in el.dataset === true
  // HTML での結果: <div id="user" data-id="1234567890" data-user="carinaanand" data-some-data-attr="mydata">Carina Anand</div>
}

仕様書

Specification
HTML Standard # dom-dataset-dev

ブラウザーの互換性

BCD tables only load in the browser