Carousel

이미지를 슬라이드 형태로 표시하고, 클릭 시 외부 콜백을 호출하는 캐러셀 컴포넌트

개요

이미지 목록을 좌우 슬라이드로 표시합니다. 화살표와 인디케이터로 탐색하며, 자동 재생(autoplay)을 지원합니다. onImageClick을 넘기면 이미지 클릭을 콜백으로 받습니다.

주요 특징

• ✅ 단일/다중 슬라이드: 이미지가 2장 이상이면 화살표와 인디케이터를 표시
• ✅ 자동 재생: autoplay/delay로 자동 슬라이드
• ✅ 화살표 모드: always, hover, never 세 가지 표시 방식
• ✅ 클릭 콜백: onImageClick을 넘기면 슬라이드가 버튼이 되고 클릭을 콜백으로 위임
• ✅ embla 옵션: opts로 loop·드래그 등 embla-carousel 옵션을 그대로 전달
• ✅ 문구: labels로 이미지 없음 alt·인디케이터 이름을 바꿈
• ✅ 슬라이드 이벤트: onSlideChange로 현재/이전 인덱스와 현재 이미지 전달

기본 사용

images에 { id, src } 목록을 전달합니다. 1장이면 화살표/인디케이터가 표시되지 않습니다.

Preview

Previous slideNext slide

슬라이드를 직접 넣기 (children)

Carousel.Item을 children으로 넣으면 이미지가 아닌 내용도 슬라이드로 쓸 수 있습니다. children을 주면 images보다 이기고, onImageClick은 적용되지 않으며 onSlideChange·ref의 currentImage는 undefined입니다. 화살표·인디케이터·자동 재생·높이·labels·opts는 그대로 적용됩니다.

Carousel.Item의 className은 슬라이드 콘텐츠 박스에 붙습니다. 슬라이드 사이 간격은 바깥 요소가 가지므로 배경을 줘도 간격까지 번지지 않습니다.

<Carousel height={240}>
  <Carousel.Item>
    <div className="flex h-full items-center justify-center">안내 1</div>
  </Carousel.Item>
  <Carousel.Item>
    <div className="flex h-full items-center justify-center">안내 2</div>
  </Carousel.Item>
</Carousel>

자동 재생 (Autoplay)

autoplay를 설정하면 지정된 delay(ms, 기본 4000) 간격으로 자동으로 슬라이드가 전환됩니다. 마우스를 올리거나 포커스가 캐러셀 안으로 들어오면 멈추고, 벗어나면 다시 재생됩니다. 운영체제의 움직임 줄이기(prefers-reduced-motion: reduce)가 켜져 있으면 자동 재생하지 않습니다.

<Carousel images={images} autoplay delay={3000} height={240} />

화살표 표시 방식 (arrows)

<Carousel images={images} arrows="hover" />

인디케이터 (indicators)

슬라이드 수만큼 점을 그려 현재 위치를 보이고, 점을 누르면 해당 슬라이드로 이동합니다. 이미지가 2장 이상일 때만 그리고 기본은 true입니다. 점의 이름은 labels.slide(n)(기본 “Slide n”)입니다.

<Carousel images={images} indicators={false} />

이미지 클릭 (onImageClick)

onImageClick을 넘기면 모든 슬라이드가 버튼으로 그려지고 클릭 시 콜백이 호출됩니다. 넘기지 않으면 클릭 동작이 없습니다. 콜백의 image는 images의 원본 항목이라, 항목에 더 실은 필드(예: link)를 그대로 되받습니다.

<Carousel
  images={[
    { id: "1", src: "...", link: "/page-a" },
    { id: "2", src: "...", link: "/page-b" },
  ]}
  onImageClick={({ image, index }) => {
    // image — 클릭된 항목 (image.link 포함)
    // index — 슬라이드 인덱스
  }}
/>

embla 옵션 (opts)

opts는 embla-carousel 옵션 객체를 그대로 넘깁니다. loop(끝에서 처음으로 이음), watchDrag(끌어서 넘기기), startIndex, align, dragFree, slidesToScroll 등을 쓸 수 있습니다. 기본값은 { loop: true, watchDrag: 슬라이드 2장 이상 }이고 넘긴 값이 이깁니다.

// 마지막 슬라이드에서 멈춘다
<Carousel images={images} opts={{ loop: false }} />
 
// 끌어서 넘기기를 끈다
<Carousel images={images} opts={{ watchDrag: false }} />

문구 (labels)

labels는 지정한 항목만 기본값(영어)을 덮습니다. 한국어 화면이면 네 항목을 모두 지정합니다.

<Carousel images={images} labels={{ slide: (n) => `Slide ${n}`, noImage: "No image" }} />

이미지 맞춤

images 경로의 이미지는 foundation Image로 그리고 object-cover로 고정해 맞춥니다. 맞춤을 바꾸는 prop은 없습니다. 다르게 맞추려면 children으로 슬라이드를 직접 넣고, Carousel.Item 안에 foundation Image를 두어 className으로 정합니다. Image는 @vortex/ui-cals에서 import합니다.

Carousel.Item의 콘텐츠 박스는 안의 Image를 박스 크기로 채웁니다. 그래서 Image에 size-full과 맞춤 클래스를 주면 슬라이드 높이(height) 안에서 맞춰집니다.

맞춤 값

보이는 영역은 object-position 클래스로 정합니다: object-center(기본), object-top, object-bottom, object-left, object-right, object-left-top 등. cover로 잘릴 때 어느 쪽을 남길지, contain·none으로 여백이 생길 때 이미지를 어디에 둘지를 정합니다.

AS-IS(el-carousel 슬라이드의 background-image, background-size: auto)는 원본 크기로 가운데에 두었습니다. 가장 가까운 것은 object-none object-center입니다.

예제

import { Carousel, Image } from "@vortex/ui-cals"
 
// 세로로 긴 이미지: 전체가 보이게 (좌우 여백)
<Carousel height={240}>
  <Carousel.Item>
    <Image src={portrait} alt="세로 이미지" className="size-full object-contain" />
  </Carousel.Item>
</Carousel>
 
// 세로로 긴 이미지: 가득 채우기 (위아래 잘림)
<Carousel height={240}>
  <Carousel.Item>
    <Image src={portrait} alt="세로 이미지" className="size-full object-cover" />
  </Carousel.Item>
</Carousel>
 
// 가로로 긴 이미지: 전체가 보이게 (위아래 여백)
<Carousel height={240}>
  <Carousel.Item>
    <Image src={panorama} alt="파노라마" className="size-full object-contain" />
  </Carousel.Item>
</Carousel>
 
// 채우되 위쪽을 남기기 (인물 사진의 얼굴 등)
<Carousel height={240}>
  <Carousel.Item>
    <Image src={portrait} alt="인물" className="size-full object-cover object-top" />
  </Carousel.Item>
</Carousel>
 
// 여러 장, 장마다 다른 맞춤
<Carousel
  height={240}
  onSlideChange={({ currentIndex }) => {
    // children 경로라 currentImage 는 undefined. currentIndex 로 구분한다
    console.log(currentIndex)
  }}
>
  <Carousel.Item>
    <Image src={portrait} alt="세로" className="size-full object-contain" />
  </Carousel.Item>
  <Carousel.Item>
    <Image src={panorama} alt="가로" className="size-full object-cover" />
  </Carousel.Item>
  <Carousel.Item>
    <Image src={icon} alt="작은 아이콘" className="size-full object-scale-down" />
  </Carousel.Item>
</Carousel>

한계

• Image는 Carousel.Item의 직계 자식으로 둡니다. 사이에 다른 래퍼(div 등)를 두면 그 래퍼에 높이가 없어 Image가 슬라이드 높이를 받지 못할 수 있습니다. 래퍼가 꼭 필요하면 래퍼에 h-full을 줍니다.
• 콘텐츠 박스가 채우는 대상은 foundation Image(data-slot="image")입니다. 일반 <img>는 size-full만으로 채워집니다.

이미지 로드 실패와 빈 목록의 동작은 아래 「이미지 없음」을 봅니다. children 경로의 Image는 foundation Image의 기본 대체 표시를 쓰고, fallbackSrc·labels.noImage는 images 경로에만 적용됩니다.

이미지 없음 (No-Image)

images가 빈 배열이거나, 항목의 src가 비었거나, 이미지 로드에 실패하면 대체 표시가 나옵니다. fallbackSrc를 지정하면 그 이미지를(alt는 labels.noImage), 없으면 아이콘을 보입니다. 로드 중에는 스켈레톤이 보입니다.

<Carousel images={[]} height={200} />

API Reference

CarouselImage

Props

Events

CarouselRef

접근성

권장 사항

• ✅ 각 이미지에 alt 텍스트를 제공하여 대체 텍스트를 노출
• ✅ 캐러셀 영역에 role="region", aria-roledescription="carousel" 부여 (Foundation 기본)
• ✅ 각 슬라이드에 role="group", aria-roledescription="slide" 부여 (Foundation 기본)
• ✅ 인디케이터에 aria-label과 aria-current로 현재 슬라이드를 표시

관련 컴포넌트

• ImageView: 확대 보기를 지원하는 이미지 뷰어
• Foundation Carousel: 기본 캐러셀 컴포넌트