Thymeleafのth:data-*属性を使いこなす！初心者向け完全解説
生徒
「先生、Thymeleafのth:data-*属性って何に使うんですか？」
先生
「良い質問ですね。Thymeleafのth:data-*属性は、HTMLのdata-*属性に動的な値を設定するときに使われます。」
生徒
「なるほど。じゃあ、具体的にはどのように書くんですか？」
先生
「それでは、th:data-*の使い方を詳しく見ていきましょう！」
1. th:data-*属性とは？
Thymeleafのth:data-*属性は、HTMLで使われるdata-*属性に、サーバー側の値を動的に埋め込むための仕組みです。data-*属性はHTMLの標準機能で、画面には直接表示されませんが、裏側で情報を持たせておく用途によく使われます。
例えば「このボタンはどのユーザーに対応しているか」「この要素はどんな種類なのか」といった情報を、HTML要素にひも付けておくことができます。Thymeleafを使えば、Java側で用意した値をそのままdata-*属性として出力できるため、画面表示とデータの受け渡しを自然につなげられます。
次の例は、ユーザーIDをdata-user-idとしてHTMLに持たせる最もシンプルな書き方です。画面には何も変わりませんが、HTMLの中には値がしっかり埋め込まれています。
<div th:data-user-id="\${user.id}">ユーザー情報</div>
このように、th:data-*属性は「見た目はそのまま、内部にデータを持たせる」ための入り口として覚えておくと理解しやすくなります。
2. th:data-*属性の基本的な使い方
ここでは、th:data-*属性の最も基本的な使い方を確認していきましょう。ポイントは「HTMLのdata-*属性に、サーバー側の値をそのまま渡せる」という点です。画面表示には影響しないため、初心者の方でも安心して使えます。
例えば、ログイン中のユーザーIDをHTML要素に持たせたい場合、次のように記述します。\${user.id}には、コントローラから渡された値が入ります。
<div th:data-user-id="\${user.id}"></div>
このテンプレートが表示されると、Thymeleafによってth:data-user-idは通常のHTML属性に変換されます。もしユーザーIDが「1001」であれば、ブラウザ上では次のようなHTMLになります。
<div data-user-id="1001"></div>
このように、th:data-*属性は「値を画面に表示せず、裏側で持たせる」ための基本形です。まずはこの書き方に慣れることで、後の応用もスムーズに理解できるようになります。
3. th:data-*属性で複数のカスタム属性を設定する
th:data-*属性は、1つの要素に対して複数のdata-*属性をまとめて設定できます。実務では「IDだけでなく、役割や状態も一緒に渡したい」といった場面がよくあるため、この書き方を覚えておくと便利です。HTMLに情報を持たせておけば、後からJavaScriptで必要な値だけ取り出して使えます。
例えば、ユーザーIDとロール（権限）を同時に埋め込みたい場合は、次のようにth:data-user-idとth:data-roleを並べて書きます。
<div th:data-user-id="\${user.id}" th:data-role="\${user.role}"></div>
もしuser.idが「1001」、user.roleが「admin」なら、ブラウザで確認できるHTMLは次のようになります（見た目は変わらず、属性として値が入ります）。
<div data-user-id="1001" data-role="admin"></div>
もう少し分かりやすくするために、ボタンに「どのユーザーの操作か」を持たせる例も見てみましょう。ボタン自体の表示はそのままですが、クリックされたときに必要な情報を取り出しやすくなります。
<button th:data-user-id="\${user.id}" th:data-role="\${user.role}">
編集
</button>
このように、複数のdata-*属性をまとめて埋め込めるのがth:data-*属性の強みです。まずは「1要素に必要な情報をセットで持たせられる」と覚えておくと、使いどころが見えてきます。
4. JavaScriptでdata-*属性を活用する
HTMLに動的に設定されたdata-*属性は、JavaScriptでも簡単に扱えます。たとえば、data-user-idの値をJavaScriptで取得するときは次のように書きます。
<script>
const divElement = document.querySelector('div');
const userId = divElement.dataset.userId;
console.log(userId);
</script>
このように、サーバーサイドから渡されたデータをJavaScriptにスムーズに受け渡すことができるのが、data-*属性の強みです。
5. th:data-*属性を使うときの注意点
th:data-*属性を使う際の注意点も確認しておきましょう。
- 属性名は必ず
data-*という形にすること。例えばdata-user-idやdata-roleなど。 - 動的に設定する値は、必ずThymeleafの式（例：
\${user.id}）を使って記述すること。 - ブラウザで確認するときは、実際のHTMLソースを見て、
data-*属性が正しく反映されているかを確認するとよいです。
6. 具体例：ユーザー情報をdata-*属性に埋め込む
実践的な例として、ユーザー情報をdata-*属性に埋め込む例を見てみましょう。たとえば、ユーザーの名前、ID、ロールをdata-*属性にまとめて設定する場合です。
<div th:data-user-id="\${user.id}" th:data-user-name="\${user.name}" th:data-user-role="\${user.role}">
\${user.name}
</div>
ブラウザ上で表示されるHTMLは次のようになります。
<div data-user-id="1001" data-user-name="太郎" data-user-role="admin">
太郎
</div>
これにより、JavaScriptでdata-user-idなどを簡単に取得し、動的な動作に活かせます。
7. まとめて覚えよう！th:data-*属性の活用ポイント
Thymeleafのth:data-*属性は、HTMLのdata-*属性に動的な値を簡単に埋め込める便利な仕組みです。特に、JavaScriptで値を取得して使いたいときや、ページ表示時にサーバーからの値を埋め込みたいときに役立ちます。
HTMLの属性として安全に値を渡せるので、テンプレートエンジンであるThymeleafとの相性も抜群です。実際のプロジェクトでも活用して、便利さを体感してくださいね！
まとめ
今回は、Thymeleafで使われる便利な属性であるth:data-*について、基本から応用までじっくりと解説しました。th:data-*は、HTMLのdata-*属性にサーバーサイドの動的な値を簡単に埋め込めるという非常に重要な機能です。とくに、JavaScriptと連携するようなWebアプリケーションでは、data-user-idやdata-roleなどの属性を使って、DOMから情報を読み取るケースが非常に多く見られます。
HTMLテンプレート内でサーバーから受け取った値を視覚的には表示せず、JavaScript処理のためだけに保持しておきたい場合など、data-*属性はきわめて有効です。これをth:data-*で効率的に指定すれば、JavaとJavaScriptの橋渡しがよりスムーズに行えます。
また、複数のdata-*属性を同時に扱うことで、ユーザー情報や状態、フラグなどの様々なデータを一括で扱える利便性もあります。今回はth:data-user-id、th:data-user-name、th:data-user-roleなどの例で解説しましたが、応用すれば非常に多くのパターンに対応できます。
さらに、JavaScriptとの組み合わせも大きなポイントでした。JavaScriptではelement.datasetを通じてdata-*属性の値に簡単にアクセスできます。そのため、Thymeleafで動的に属性を設定し、それをJavaScriptで処理するという自然な連携が可能になります。
注意点としては、属性名の命名ルール（data-で始める）を守ること、Thymeleafの式を正しく記述すること、そして表示されたHTMLで実際に反映されているか確認することが大切です。
こうしたポイントを意識するだけで、Thymeleafテンプレートの記述がより強力になり、複雑なアプリケーションでも柔軟に対応できるようになります。特にフロントエンドとバックエンドが密接に連携する開発では、th:data-*を覚えておくと非常に助かります。
最後に、今回の学習内容を簡単なサンプルコードとしてまとめておきます。実際にプロジェクトに取り入れて、理解を深めてみてください。
サンプル：ユーザーデータをdata属性に埋め込む
<div th:data-user-id="${user.id}"
th:data-user-name="${user.name}"
th:data-user-role="${user.role}">
${user.name}
</div>
このような記述で、Javaオブジェクトの値をそのままHTMLに反映し、JavaScript側で取り出して使えるようになります。
生徒
「先生、th:data-*属性ってこんなに便利だったんですね。JavaScriptと連携させる場面で大活躍しそうです！」
先生
「その通りです。HTMLの見た目には影響を与えずにデータを持たせる方法として、data-*属性は非常に使いやすいんですよ。」
生徒
「ユーザーIDや権限のような情報をサーバー側で埋め込んで、フロントで処理できるって便利ですね。」
先生
「JavaとJavaScriptの中継点としても使えるので、今後の開発でもたくさん登場するはずですよ。セキュリティにも注意しながら活用してくださいね。」
生徒
「はい、表示には出さず、JavaScriptだけが使うってところもポイントですね。これからは積極的に使ってみます！」
先生
「素晴らしい心がけです。習ったことは、実際にプロジェクトで試すことで本当に身につきますよ。」
この記事を読んだ人からの質問
