Reactで、横にめくれる画像のカルーセルを作る方法

import { useRef, useState } from 'react';

type Slide = { src: string; alt: string };

type Props = {
  label: string;
  slides: Slide[];
};

export function ImageCarousel({ label, slides }: Props) {
  const [index, setIndex] = useState(0);
  const trackRef = useRef<HTMLDivElement>(null);
  const last = slides.length - 1;

  // スクロールの位置から、いま見えているスライドの番号を求める
  const handleScroll = () => {
    const track = trackRef.current;
    if (!track) return;
    setIndex(Math.round(track.scrollLeft / track.clientWidth));
  };

  // scrollIntoView ではなく、枠の中だけをスクロールする
  const goTo = (i: number) => {
    const track = trackRef.current;
    if (!track) return;
    track.scrollTo({ left: i * track.clientWidth, behavior: 'smooth' });
  };

  return (
    <section className="carousel" aria-roledescription="carousel" aria-label={label}>
      <div className="carousel-track" ref={trackRef} onScroll={handleScroll} tabIndex={0}>
        {slides.map((slide, i) => (
          <div
            key={slide.src}
            className="carousel-slide"
            role="group"
            aria-roledescription="slide"
            aria-label={`${i + 1} / ${slides.length}`}
          >
            <img src={slide.src} alt={slide.alt} loading="lazy" draggable={false} />
          </div>
        ))}
      </div>
      <div className="carousel-controls">
        <button type="button" onClick={() => goTo(index - 1)} disabled={index === 0} aria-label="前の画像">
          ‹
        </button>
        <span className="carousel-count" aria-hidden="true">
          {index + 1} / {slides.length}
        </span>
        <button type="button" onClick={() => goTo(index + 1)} disabled={index === last} aria-label="次の画像">
          ›
        </button>
      </div>
    </section>
  );
}

.carousel {
  max-width: 400px;
}
.carousel-track {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
  scrollbar-width: none;
}
.carousel-slide {
  flex: 0 0 100%;
  scroll-snap-align: start;
}
.carousel-slide img {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}
.carousel-controls {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 16px;
  margin-top: 8px;
}
.carousel-controls button {
  width: 44px;
  height: 44px;
  font-size: 24px;
}

const slides = [
  { src: 'images/slide-1.svg', alt: '1枚目の画像' },
  { src: 'images/slide-2.svg', alt: '2枚目の画像' },
  // …
];

<ImageCarousel label="作例の写真" slides={slides} />

scroll-snap あり（ImageCarousel）: 16msごとに左へ80px動かして離す → scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
scroll-snap あり（ImageCarousel）: 16msごとに左へ160px動かして離す → scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
scroll-snap あり（ImageCarousel）: 16msごとに左へ240px動かして離す → scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
scroll-snap あり（ImageCarousel）: 150msごとに左へ80px動かして離す → scrollLeft=0 表示=1/5 前へ=押せない 次へ=押せる
scroll-snap あり（ImageCarousel）: 150msごとに左へ160px動かして離す → scrollLeft=0 表示=1/5 前へ=押せない 次へ=押せる
scroll-snap あり（ImageCarousel）: 150msごとに左へ240px動かして離す → scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
scroll-snap-type: none の版: 16msごとに左へ80px動かして離す → scrollLeft=68 表示=1/5 前へ=押せない 次へ=押せる
scroll-snap-type: none の版: 16msごとに左へ160px動かして離す → scrollLeft=156 表示=1/5 前へ=押せない 次へ=押せる
scroll-snap-type: none の版: 16msごとに左へ240px動かして離す → scrollLeft=241 表示=2/5 前へ=押せる 次へ=押せる
scroll-snap-type: none の版: 150msごとに左へ80px動かして離す → scrollLeft=65 表示=1/5 前へ=押せない 次へ=押せる
scroll-snap-type: none の版: 150msごとに左へ160px動かして離す → scrollLeft=145 表示=1/5 前へ=押せない 次へ=押せる
scroll-snap-type: none の版: 150msごとに左へ240px動かして離す → scrollLeft=225 表示=2/5 前へ=押せる 次へ=押せる

最初: scrollLeft=0 表示=1/5 前へ=押せない 次へ=押せる
次へ 1回目: scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
次へ 2回目: scrollLeft=800 表示=3/5 前へ=押せる 次へ=押せる
次へ 3回目: scrollLeft=1200 表示=4/5 前へ=押せる 次へ=押せる
次へ 4回目: scrollLeft=1600 表示=5/5 前へ=押せる 次へ=押せない
前へ 1回: scrollLeft=1200 表示=4/5 前へ=押せる 次へ=押せる

slide.scrollIntoView(): ページの scrollY 610 → 1200、カルーセルの scrollLeft=400
slide.scrollIntoView({ block: 'nearest', inline: 'start' }): ページの scrollY 610 → 725、カルーセルの scrollLeft=400
track.scrollTo({ left })（ImageCarousel）: ページの scrollY 610 → 610、カルーセルの scrollLeft=400

Tab でフォーカスした要素: carousel-track
ArrowRight: scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
ArrowRight: scrollLeft=800 表示=3/5 前へ=押せる 次へ=押せる
ArrowLeft: scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
End: scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる
Home: scrollLeft=400 表示=2/5 前へ=押せる 次へ=押せる

- region "作例の写真":
  - group "1 / 5":
    - img "1枚目の画像"
  - group "2 / 5":
    - img "2枚目の画像"
  - group "3 / 5":
    - img "3枚目の画像"
  - group "4 / 5":
    - img "4枚目の画像"
  - group "5 / 5":
    - img "5枚目の画像"
  - button "前の画像" [disabled]: ‹
  - button "次の画像": ›

scroll-snap あり（ImageCarousel）: 幅400px scrollLeft=800 表示=3/5 前へ=押せる 次へ=押せる → 幅320px scrollLeft=640 表示=3/5 前へ=押せる 次へ=押せる
scroll-snap-type: none の版: 幅400px scrollLeft=800 表示=3/5 前へ=押せる 次へ=押せる → 幅320px scrollLeft=800 表示=3/5 前へ=押せる 次へ=押せる

loading="lazy"（ImageCarousel）: loading=lazy 開いた直後に読み込んだ画像: 1,2,3,4,5
loading 属性なしの版: loading=null 開いた直後に読み込んだ画像: 1,2,3,4,5,6,7,8