ステッパー

hc-stepper はマルチステップフローの進行を表示します。JavaScript を一切同梱しません: サーバがステップのたびにインジケーター全体 — マーカーの内容(ステップ番号、完了したら ✓)を含む — を描画するため、すべての状態変化はマークアップとして届きます。インジケーターは表示し、ナビゲーションはステップのフォームの仕事です (マルチステップフォームレシピを参照)。

別名: ウィザードステップ、進行ステップ。

基本の HTML

Account (completed)
Profile
Review

<ol class="hc-stepper">
  <li class="hc-stepper__step" data-state="complete">
    <span class="hc-stepper__marker" aria-hidden="true">✓</span>
    <span class="hc-stepper__label">Account
      <span class="hc-sr-only">(completed)</span></span>
  </li>
  <li class="hc-stepper__step" aria-current="step">
    <span class="hc-stepper__marker" aria-hidden="true">2</span>
    <span class="hc-stepper__label">Profile</span>
  </li>
  <li class="hc-stepper__step">
    <span class="hc-stepper__marker" aria-hidden="true">3</span>
    <span class="hc-stepper__label">Review</span>
  </li>
</ol>

状態

状態	セレクタ	効果
現在	`[aria-current="step"]`	アクセントのマーカー(`data-color` に追従)、強調されたラベル。
完了	`[data-state="complete"]`	ティントのマーカー。サーバがマーカー内容として `✓` を描画。
未到達	(属性なし)	ミュートのマーカーとラベル。

マーカーの内容はサーバが描画します。 保留中のステップには番号、完了したものには ✓ — CSS content の小細工も、クライアントの変更もありません。完了したラベルには視覚的に隠した (completed) の接尾辞を足して状態が読み上げられるようにします。現在のステップは aria-current="step" がカバーします。

クリック可能な完了ステップ

フローが再訪を許すなら、完了ステップの内容をそのステップ URL へのリンクとして描画してください — ステッパーはそれを控えめにスタイルします(ホバー / フォーカスで下線)。これはステップごとのサーバの選択です。インジケーターがナビゲーションを発明することはありません。カラムレイアウトを保つため、マーカーはリンクの外に置いてください:

Account (completed)
Profile
Review

<li class="hc-stepper__step" data-state="complete">
  <span class="hc-stepper__marker" aria-hidden="true">✓</span>
  <a href="/checkout/account">
    <span class="hc-stepper__label">Account
      <span class="hc-sr-only">(completed)</span></span>
  </a>
</li>

サイズ

data-size="sm" は密なレイアウト向けにマーカーを縮めます。水平のみ — 縦の向きは当面の意図的な非目標です。

Account (completed)
Profile
Review

<ol class="hc-stepper" data-size="sm">
  <!-- …the same steps… -->
</ol>

htmx での利用

サーバはステップのたびにインジケーター全体を再描画します: ステップのフォームのレスポンス (マルチステップフォームレシピを参照)が、aria-current を移した <ol> をそのまま含めるだけです。ステップ 1 の完了後、サーバはこう返します:

<ol class="hc-stepper">
  <li class="hc-stepper__step" data-state="complete">
    <span class="hc-stepper__marker" aria-hidden="true">✓</span>
    <span class="hc-stepper__label">Account
      <span class="hc-sr-only">(completed)</span></span>
  </li>
  <li class="hc-stepper__step" aria-current="step">
    <span class="hc-stepper__marker" aria-hidden="true">2</span>
    <span class="hc-stepper__label">Profile</span>
  </li>
  <!-- …remaining steps unchanged (upcoming) -->
</ol>

クライアントの変更はありません: マーカーの内容(✓ / 2)、 data-state、aria-current のすべてがマークアップとして届きます。

アクセシビリティ

順序つきリストが正しい骨格です:「リスト、3 項目」+ aria-current="step" が標準のイディオムです。
マーカーは aria-hidden(位置の装飾的な複製)です。意味を運ぶのはラベルのテキスト + sr-only の接尾辞です。
RTL は無料で機能します(コネクタを含め、全体が論理プロパティ)。

テーマ用トークン

component トークン(component.tokens.json)— semantic 参照なので、テーマ、アクセント、ダークモードが自動で適用されます:

トークンパス	用途
`stepper.marker-size`	マーカーの直径(`data-size="sm"` が上書き)。
`stepper.marker-bg` / `marker-fg`	未到達ステップのマーカー。
`stepper.current-bg` / `current-fg`	現在ステップのマーカー(`data-color` に追従)。
`stepper.complete-bg` / `complete-fg`	完了ステップのマーカーのティント。
`stepper.connector`	ステップ間のコネクタ線。
`stepper.label`	ラベルの色。
`stepper.gap`	マーカーとラベルの間隔。

CSS 変数

生成される CSS 変数を表示

--hc-stepper-marker-size | -marker-bg | -marker-fg
--hc-stepper-current-bg | -current-fg
--hc-stepper-complete-bg | -complete-fg
--hc-stepper-connector | -label | -gap