カルーセル

hc-carousel は、ネイティブのスクロール位置が信頼できる唯一の情報源 であるカルーセルです。スライドは CSS スクロールスナップのレールに置かれ、 installCarousel() が表示中のスライドを追跡し、前へ / 次へとドットの コントロールを同期し、キーボードサポートを追加し、オプトインの自動再生 を提供します。アニメーションライブラリも JS 駆動の transform も ありません — 動きはネイティブのスムーズスクロールが担います。

別名: スライダー、スライドショー。

基本の HTML

PreviewCode

Slide 1

Slide 2

Slide 3

‹›

<div class="hc-carousel" aria-label="Featured">
  <div class="hc-carousel__viewport">
    <div class="hc-carousel__slide">…</div>
    <div class="hc-carousel__slide">…</div>
    <div class="hc-carousel__slide">…</div>
  </div>
  <button class="hc-carousel__prev" type="button" data-hc-carousel-prev aria-label="Previous slide">‹</button>
  <button class="hc-carousel__next" type="button" data-hc-carousel-next aria-label="Next slide">›</button>
  <div class="hc-carousel__dots" data-hc-carousel-dots role="group" aria-label="Choose slide"></div>
</div>

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

installCarousel() は冪等で、アンインストーラを返します。ゼロ設定の @hypermedia-components/core/behaviors エントリが自動インストールします。

installCarousel() がすること

• IntersectionObserver で最も見えているスライドを追跡し、 data-active の印を付けます(アクティブなスライドはこの属性を基に スタイルします)。
• [data-hc-carousel-dots] コンテナにスライドごとに 1 つのドットを 生成し(または作者が用意した [data-hc-carousel-dot] ボタンを 再利用し)、aria-current を同期し続けます。
• 両端で前へ / 次へボタンを無効化します。
• 前へ / 次へ / ドットのクリック、およびレールのフォーカス中の ←/→ で スクロールします — 常にネイティブのスムーズスクロール経由です。
• 変更のたびに detail.index つきのバブリングする hc:carouselchange を発行します。

事前レンダリングされるドット

[data-hc-carousel-dots] コンテナに [data-hc-carousel-dot] ボタンが すでに含まれている場合、ビヘイビアは自前で生成する代わりにそれらを 再利用します — n 番目のボタンが n 番目のスライドを制御し(文書順で 対応)、その上にクリックの配線と aria-current の同期を追加します。 初期 HTML にドット行を含めたいとき(ビヘイビアの読み込み中もレイアウト シフトなし)は、サーバサイドでレンダリングしてください:

<div class="hc-carousel__dots" data-hc-carousel-dots role="group" aria-label="Choose slide">
  <button type="button" class="hc-carousel__dot" data-hc-carousel-dot aria-label="Go to slide 1"></button>
  <button type="button" class="hc-carousel__dot" data-hc-carousel-dot aria-label="Go to slide 2"></button>
  <button type="button" class="hc-carousel__dot" data-hc-carousel-dot aria-label="Go to slide 3"></button>
</div>

スライドの幅

各スライドはデフォルトでビューポートを満たします (--hc-carousel-slide-size: 100%)。複数アイテムのレールにするには、 スライドのベースを設定して複数を同時に表示します:

PreviewCode

Slide 1

Slide 2

Slide 3

Slide 4

‹›

<div class="hc-carousel" style="--hc-carousel-slide-size: 50%">…</div>

自動再生(オプトイン、モーションセーフ)

data-autoplay="<ms>" を足すと自動で進みます。オプトインのみで、 次の性質を持ちます:

• ホバーとフォーカスで一時停止します(ポインタやキーボードの下から コンテンツが動き去ることが決してないように)。
• prefers-reduced-motion: reduce では完全に無効です — 動きを 避けたいユーザーに自動の動きはありません。

<div class="hc-carousel" data-autoplay="4000" aria-label="Promos">…</div>

htmx での利用

スライドは素の HTML なので、パーシャルとして遅延読み込みできます — 例えばレールをサーバサイドで描画したり、htmx でビューポートに追加の スライドをスワップしたり。ビヘイビアは追加された .hc-carousel ルートを MutationObserver で再スキャンします。既存のカルーセルに 追加されたスライドには installCarousel() を再実行してください。

アクセシビリティ

• カルーセルに aria-label を与えてください。レールはフォーカス可能な 領域(aria-roledescription="carousel")として公開されるため、←/→ が機能し、スクロールコンテナはキーボードで到達可能です。
• 各スライドは aria-roledescription="slide" と aria-label (デフォルトは「1 of 3」— よりよいタイトルがあればスライドごとに 上書き)を持つ group です。
• 前へ / 次へ / ドットのコントロールはラベルつきの本物の <button> です。ドットは aria-current でアクティブなスライドを公開します。
• 自動再生のホバー / フォーカスでの一時停止と reduced-motion での オプトアウトは中核のアクセシビリティ保証です — 維持してください。

テーマ用トークン

トークンパス	用途
carousel.gap	スライド間のギャップ。
carousel.slide-size	スライドの flex-basis(デフォルト 100%)。
carousel.control-size	前へ / 次へボタンの直径。
carousel.control-bg / -fg / -border	前へ / 次へボタンの色。
carousel.control-offset	前へ / 次へボタンのインセット。
carousel.dot-size / -gap	ドットのサイズと間隔。
carousel.dot-color / -active-color	ドットとアクティブドットの色。
carousel.dots-margin	ドット行の上のギャップ。

CSS 変数

生成される CSS 変数を表示

--hc-carousel-gap | -slide-size
--hc-carousel-control-size | -control-bg | -control-fg | -control-border | -control-offset
--hc-carousel-dot-size | -dot-gap | -dot-color | -dot-active-color | -dots-margin

関連

• スクロールエリア — エッジシャドウつきの素のスクロール領域(スナップやコントロールは なし)。
• タブ — レールをスクロール するのではなく、パネルを切り替えます。