Carousel
여러 콘텐츠를 가로 슬라이드 방식으로 순차 표시하는 컴포넌트
개요
Carousel 컴포넌트는 embla-carousel 기반으로 슬라이드 콘텐츠를 순차적으로 표시합니다. 이전/다음 버튼, 인디케이터, 자동 재생, 반복, 스와이프 등 다양한 기능을 지원합니다.
주요 특징
- ✅ 이전/다음 버튼: 좌/우 이동 버튼
- ✅ 인디케이터: 현재 위치 및 전체 슬라이드 수 표시
- ✅ 자동 재생: 플러그인을 통한 자동 슬라이드 전환
- ✅ 자동 재생 제어: 재생/정지 토글, Hover 시 정지
- ✅ 반복 여부 설정: 순환(loop) 모드
- ✅ 초기 슬라이드 설정: 시작 인덱스 지정
- ✅ 스와이프: 터치 환경 스와이프 제스처
- ✅ 데이터 바인딩: 배열 데이터 기반 동적 슬라이드
- ✅ 접근성: ARIA 속성 지원
기본 상태
Preview
기본 Carousel UI로, CarouselContent 안에 CarouselItem을 배치하고 이전/다음 버튼을 제공합니다.
Viewport 영역 / 콘텐츠 크기 통일
CarouselItem의 basis 클래스로 한 번에 표시할 슬라이드 개수를 제어할 수 있습니다. 모든 슬라이드는 동일한 구조 및 크기를 유지합니다.
Preview
basis-1/3을 적용하여 한 번에 3개 슬라이드를 표시합니다.
인디케이터 표시 / 인디케이터 이동
setApi를 통해 Carousel API에 접근하여 인디케이터를 구현할 수 있습니다. 인디케이터 클릭 시 해당 슬라이드로 이동합니다.
Preview
setApi로 API를 받아 scrollSnapList, selectedScrollSnap, scrollTo를 활용합니다.
자동 재생 / 자동 재생 간격
embla-carousel-autoplay 플러그인으로 자동 재생을 지원합니다. delay 옵션으로 전환 간격을 설정합니다.
Preview
2초 간격으로 자동 전환되며, Hover 시 일시정지됩니다.
자동 재생 제어
사용자 조작 시 자동 재생을 일시 정지하거나, 버튼으로 재생/정지를 제어할 수 있습니다.
Preview
plugin.play(), plugin.stop()으로 재생/정지를 토글합니다.
반복 여부 설정
opts.loop를 true로 설정하면 마지막 슬라이드 이후 첫 슬라이드로 순환합니다.
Preview
loop: true 설정으로 무한 순환됩니다.
초기 슬라이드 설정
opts.startIndex로 초기 진입 시 표시할 슬라이드를 지정할 수 있습니다.
Preview
startIndex: 2로 3번째 슬라이드부터 시작합니다.
API Reference
컴포넌트 구조
| 컴포넌트 | HTML 요소 | Description |
|---|---|---|
Carousel | <div> | 최상위 컨테이너 |
CarouselContent | <div> | 슬라이드 래퍼 (Viewport) |
CarouselItem | <div> | 개별 슬라이드 |
CarouselPrevious | <button> | 이전 버튼 |
CarouselNext | <button> | 다음 버튼 |
Carousel Props
| Prop | Type | Default | Description |
|---|---|---|---|
opts | CarouselOptions | - | embla-carousel 옵션 |
plugins | CarouselPlugin | - | embla-carousel 플러그인 |
orientation | "horizontal" | "vertical" | "horizontal" | 슬라이드 방향 |
setApi | (api: CarouselApi) => void | - | API 인스턴스 콜백 |
className | string | - | 추가 CSS 클래스 |
CarouselOptions (주요 옵션)
| Option | Type | Default | Description |
|---|---|---|---|
loop | boolean | false | 순환 모드 |
startIndex | number | 0 | 시작 슬라이드 인덱스 |
align | string | - | 슬라이드 정렬 (start, center, end) |
CarouselApi (주요 메서드)
| Method | Description |
|---|---|
scrollPrev() | 이전 슬라이드로 이동 |
scrollNext() | 다음 슬라이드로 이동 |
scrollTo(index) | 특정 슬라이드로 이동 |
canScrollPrev() | 이전 이동 가능 여부 |
canScrollNext() | 다음 이동 가능 여부 |
scrollSnapList() | 전체 스냅 포인트 목록 |
selectedScrollSnap() | 현재 선택된 스냅 인덱스 |
Events
| Event | Description |
|---|---|
select | 슬라이드 선택 시 |
reInit | 캐러셀 재초기화 시 |
기본 사용법
import {
Carousel,
CarouselContent,
CarouselItem,
CarouselPrevious,
CarouselNext,
} from "@vortex/ui-foundation"
<Carousel>
<CarouselContent>
<CarouselItem>Slide 1</CarouselItem>
<CarouselItem>Slide 2</CarouselItem>
<CarouselItem>Slide 3</CarouselItem>
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>접근성
ARIA 속성
Carousel:role="region",aria-roledescription="carousel"CarouselItem:role="group",aria-roledescription="slide"- 이전/다음 버튼:
sr-only텍스트 포함
권장 사항
- ✅ 키보드 좌/우 화살표로 슬라이드 이동 지원
- ✅ 자동 재생 시 일시정지 컨트롤 제공
- ❌ 자동 재생만으로 콘텐츠를 제공하지 않음 (수동 이동 병행)