ツールチップ

hc-tooltip は、popover 要素をトリガーを説明する小さなラベルとしてスタイルします。トリガーは aria-describedby でツールチップを参照するため、トリガーがフォーカスを受けるとスクリーンリーダーが説明を読み上げます。installTooltip() がホバー、フォーカス、Escape での視覚的な表示 / 非表示を処理します。

別名: ヒント、吹き出し。

ブラウザのベースライン

プリミティブ	必要バージョン
HTML `popover`	Chrome 114、Edge 114、Firefox 125、Safari 17
CSS Anchor Positioning	Chrome 125、Edge 125、Firefox 147、Safari 26

Anchor Positioning のないブラウザは getBoundingClientRect ベースの配置フックへフォールバックするため、ツールチップは引き続きトリガーの上に現れます。popover がサポートされる環境ならどこでもツールチップは機能します。

新しい popover="hint" ではなく popover="manual" を使うのは、2026 年 5 月時点で Safari に hint サポートがなかったためです。manual + JS トグルは、 popover をサポートするすべてのブラウザで hint のセマンティクス — 別々のツールチップが互いを解散させず共存する — に一致します。

基本の HTML

<button class="hc-button" type="button" aria-describedby="save-tip">
  <span aria-hidden="true">💾</span>
  <span>Save</span>
</button>
<div class="hc-tooltip" id="save-tip">Save document (Ctrl+S)</div>

<button class="hc-button" type="button" aria-describedby="delete-tip"
        data-variant="error">
  <span aria-hidden="true">🗑️</span>
  <span>Delete</span>
</button>
<div class="hc-tooltip" id="delete-tip">Move to trash</div>

import { installTooltip } from '@hypermedia-components/core';
installTooltip();

installTooltip() は冪等で、アンインストーラを返します。ゼロ設定の @hypermedia-components/core/behaviors エントリが自動インストールし、 htmx でスワップされた内容も自動で拾います。

`installTooltip()` がすること

作者が付けていなければ、ツールチップ要素に属性を自動付与します: popover="manual"(表示 / 非表示の完全な JS 制御)と role="tooltip"(スクリーンリーダーのセマンティクス)。
aria-describedby でツールチップを参照するすべてのトリガーを配線します — 1 つのツールチップが複数のトリガーに仕えられます。
対応する anchor-name(アクティブなトリガー)と position-anchor(ツールチップ)を注入し、CSS Anchor Positioning でツールチップがトリガーの上に着地します。別の共有トリガーがホバー / フォーカスされたらアンカーを結び直します。
表示 / 非表示のタイミング:
- mouseenter → 300 ms の遅延後に表示(業界標準の「ホバーの意図」しきい値)。
- mouseleave → 100 ms の猶予後に非表示(遅延中なら保留中の表示をキャンセル)。
- focus → 即座に表示(キーボードユーザーには遅延なし — APG のガイダンス)。
- blur → 即座に非表示。
- フォーカス中の Escape → フォーカスを動かさずに非表示。

配置

ツールチップはデフォルトでトリガーの上に置かれます。インスタンス単位で data-side(top / right / bottom / left)と任意の data-align(start / center / end、デフォルト center)で上書きします。小さなポインタには data-arrow を足します。

<button aria-describedby="hint">Help</button>
<div class="hc-tooltip" id="hint" data-side="right" data-arrow>
  Appears to the right
</div>

配置は、サポートされる環境では CSS Anchor Positioning (position-area)を、そうでなければデフォルト配置と同じ JS フォールバックを使います — data-side / data-align が両パスを同一に駆動します。共有の機構 — 両パス、矢印、--hc-anchored-* のオフセット / 矢印ノブ — は基礎 → アンカー配置にドキュメントがあります。この機構は 2026 年に Baseline へ到達し、古いエンジンには JS フォールバックがあります。

`title` 属性ではなく本物の説明を

title 属性から描画されるブラウザのネイティブツールチップはスタイルできず、プラットフォーム間で挙動が一貫せず、タッチデバイスでは現れません。hc-tooltip + aria-describedby パターンを選んでください。どうしても title を残すなら、ビヘイビアは衝突しません — しかしブラウザがあなたのツールチップの上に自身のツールチップを描画するので、取り除いてください。

アクセシビリティ

ツールチップは常にトリガーから aria-describedby="<tooltip-id>" で参照してください。視覚的なツールチップが描画されているかにかかわらず、トリガーがフォーカスを得るとスクリーンリーダーがツールチップのテキストを読み上げます。
ツールチップは短いテキストラベル専用です。インタラクティブなコンテンツ(ボタン、フォームフィールド)が必要なら、代わりにポップオーバーかダイアログを使ってください。ツールチップの面は pointer-events: none なのでクリックをインターセプトできません。
トリガーがフォーカスを保つ間、ツールチップは到達可能であり続けなければなりません — タイマーで隠さないでください。ビヘイビアはフォーカス保持中に自動解散しません。閉じるのは Escape、 blur、mouseleave だけです。
タッチデバイスにはホバーイベントがありません。ビヘイビアは長押し → 表示をポリフィルしません。トリガーのアクセシブルな名前が本質的な意味を運び、ツールチップはそれを補強する、という前提で設計してください。

テーマ用トークン

component トークン(component.tokens.json):

トークンパス	用途
`tooltip.bg` / `fg`	面とテキストの色。慣例に従いデフォルトはライト上のダーク。
`tooltip.radius`	角丸。
`tooltip.padding-x` / `padding-y`	内側のパディング。
`tooltip.font-size`	テキストサイズ。
`tooltip.max-width`	折り返しまでの上限。
`tooltip.offset`	トリガーとツールチップの距離。

CSS 変数

生成される CSS 変数を表示

--hc-tooltip-bg | -fg | -radius
--hc-tooltip-padding-x | -padding-y | -font-size
--hc-tooltip-max-width | -offset