目次

hc-toc は、ページ内アンカーリンクのリストを包むラベルつき <nav> の上の純 CSS スキンです — 長いリファレンスページでおなじみの 「このページ内」ジャンプリスト。JavaScript なしで機能します。 data-hc-spy を足せば、installSpy ビヘイビアが、読者のスクロールに合わせて表示中のセクションのリンクに 印を付けます。

別名: 目次、ページ内ナビゲーション。

基本の HTML

下のアクティブリンクは、スタイリングを見せるために aria-current="location" を静的に付けています。data-hc-spy があれば ビヘイビアが設定してくれます。

PreviewCode

• Inputs
• SQL
• Tests

<nav class="hc-toc" aria-label="On this page">
  <ul class="hc-toc__list">
    <li class="hc-toc__item"><a class="hc-toc__link" href="#sec-inputs">Inputs</a></li>
    <li class="hc-toc__item"><a class="hc-toc__link" href="#sec-sql">SQL</a></li>
    <li class="hc-toc__item"><a class="hc-toc__link" href="#sec-tests">Tests</a></li>
  </ul>
</nav>

<li class="hc-toc__item"> のラッパーは任意です — スタイリングは .hc-toc__list / .hc-toc__link をキーにするため、nav 直下の平坦な リンク列でも機能します。

スクロールスパイ(data-hc-spy)

nav に data-hc-spy を足してビヘイビアをインストールします。各リンクの #fragment をターゲットセクションに解決し、IntersectionObserver で 観測して、ビューポート上端にあるセクションのリンクへ aria-current="location" と data-active フックの印を付けます。

セットアップ

スクロールスパイには installSpy() ビヘイビアが必要です。 import '@hypermedia-components/core/behaviors'; で全ビヘイビアを一括 インストールするか、これだけを:

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

installSpy() は冪等で、アンインストーラを返し、htmx でスワップされた nav も自動で拾います。 インストールを参照。

<nav class="hc-toc" data-hc-spy aria-label="On this page">
  <a class="hc-toc__link" href="#sec-inputs">Inputs</a>
  <a class="hc-toc__link" href="#sec-sql">SQL</a>
  <a class="hc-toc__link" href="#sec-tests">Tests</a>
</nav>
…
<section id="sec-inputs">…</section>
<section id="sec-sql">…</section>
<section id="sec-tests">…</section>

ビヘイビアは存在するセクションだけを追跡し、リンクの解決はインストール 時に一度だけ行います(追跡対象のコンテンツをスワップしたら再インストール してください)。スムーススクロールを強制することは決してありません — リンクのクリックはブラウザネイティブのアンカージャンプです — なので prefers-reduced-motion がゲートすべきものもありません。

状態

状態	設定方法	スタイリング
アクティブなセクション	installSpy が aria-current="location" + data-active を設定(直接書いても可)	--hc-toc-active-fg、--hc-toc-active-font-weight、inline-start のマーカー(--hc-toc-active-marker)
ホバー	:hover	--hc-toc-link-fg → --hc-toc-link-hover-fg
フォーカス	:focus-visible	--hc-color-focus-ring の 2px アウトライン

アクティブのルールは [aria-current="location"] と [data-active] の 両方に一致するため、ハイライトはビヘイビア由来でもサーバレンダリング されたマークアップ由来でも機能します。

アクセシビリティ

• <nav> にラベルを付け(aria-label="On this page" または aria-labelledby)、ランドマークに名前を与えてください。
• アクティブなリンクは aria-current="location" を運びます — 「集合内の現在位置」を表す ARIA の値で、視覚状態とスクリーン リーダーのシグナルの両方を駆動します。
• JavaScript なしでも、nav は機能するアンカーリンクのリストのまま (アクティブハイライトなし)です — プログレッシブエンハンスメント。
• フォーカスアウトラインを保ってください。デフォルトはシステムの他の 部分に合わせて --hc-color-focus-ring を使います。

テーマ用トークン

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

トークンパス	用途
toc.font-size	リスト全体のテキストサイズ。
toc.gap	リンク間の縦のスペース。
toc.indent	inline-start のパディング(アクティブマーカーの余地)。
toc.link.fg / hover-fg	非アクティブなリンクの色(平常時とホバー)。
toc.active.fg / font-weight	アクティブなリンクの見た目。
toc.active.marker	アクティブリンクの inline-start マーカーの色。

CSS 変数

生成される CSS 変数を表示

--hc-toc-font-size | -gap | -indent
--hc-toc-link-fg | -link-hover-fg
--hc-toc-active-fg | -active-font-weight | -active-marker
--hc-color-focus-ring   (inherited from data-color)

関連

• パンくずリスト — サイトルートから現在のページまでの道筋。
• タブ — 兄弟セクション間の切り替え。