Skip to Content

Carousel

여러 콘텐츠를 가로 슬라이드 방식으로 순차 표시하는 컴포넌트


개요

Carousel 컴포넌트는 embla-carousel 기반으로 슬라이드 콘텐츠를 순차적으로 표시합니다. 이전/다음 버튼, 인디케이터, 자동 재생, 반복, 스와이프 등 다양한 기능을 지원합니다.

주요 특징

  • 이전/다음 버튼: 좌/우 이동 버튼
  • 인디케이터: 현재 위치 및 전체 슬라이드 수 표시
  • 자동 재생: 플러그인을 통한 자동 슬라이드 전환
  • 자동 재생 제어: 재생/정지 토글, Hover 시 정지
  • 반복 여부 설정: 순환(loop) 모드
  • 초기 슬라이드 설정: 시작 인덱스 지정
  • 스와이프: 터치 환경 스와이프 제스처
  • 데이터 바인딩: 배열 데이터 기반 동적 슬라이드
  • 접근성: ARIA 속성 지원

기본 상태

기본 Carousel UI로, CarouselContent 안에 CarouselItem을 배치하고 이전/다음 버튼을 제공합니다.


Viewport 영역 / 콘텐츠 크기 통일

CarouselItem의 basis 클래스로 한 번에 표시할 슬라이드 개수를 제어할 수 있습니다. 모든 슬라이드는 동일한 구조 및 크기를 유지합니다.

basis-1/3을 적용하여 한 번에 3개 슬라이드를 표시합니다.


인디케이터 표시 / 인디케이터 이동

setApi를 통해 Carousel API에 접근하여 인디케이터를 구현할 수 있습니다. 인디케이터 클릭 시 해당 슬라이드로 이동합니다.

setApi로 API를 받아 scrollSnapList, selectedScrollSnap, scrollTo를 활용합니다.


자동 재생 / 자동 재생 간격

embla-carousel-autoplay 플러그인으로 자동 재생을 지원합니다. delay 옵션으로 전환 간격을 설정합니다.

2초 간격으로 자동 전환되며, Hover 시 일시정지됩니다.


자동 재생 제어

사용자 조작 시 자동 재생을 일시 정지하거나, 버튼으로 재생/정지를 제어할 수 있습니다.

plugin.play(), plugin.stop()으로 재생/정지를 토글합니다.


반복 여부 설정

opts.looptrue로 설정하면 마지막 슬라이드 이후 첫 슬라이드로 순환합니다.

loop: true 설정으로 무한 순환됩니다.


초기 슬라이드 설정

opts.startIndex로 초기 진입 시 표시할 슬라이드를 지정할 수 있습니다.

startIndex: 2로 3번째 슬라이드부터 시작합니다.


API Reference

컴포넌트 구조

컴포넌트HTML 요소Description
Carousel<div>최상위 컨테이너
CarouselContent<div>슬라이드 래퍼 (Viewport)
CarouselItem<div>개별 슬라이드
CarouselPrevious<button>이전 버튼
CarouselNext<button>다음 버튼
PropTypeDefaultDescription
optsCarouselOptions-embla-carousel 옵션
pluginsCarouselPlugin-embla-carousel 플러그인
orientation"horizontal" | "vertical""horizontal"슬라이드 방향
setApi(api: CarouselApi) => void-API 인스턴스 콜백
classNamestring-추가 CSS 클래스

CarouselOptions (주요 옵션)

OptionTypeDefaultDescription
loopbooleanfalse순환 모드
startIndexnumber0시작 슬라이드 인덱스
alignstring-슬라이드 정렬 (start, center, end)

CarouselApi (주요 메서드)

MethodDescription
scrollPrev()이전 슬라이드로 이동
scrollNext()다음 슬라이드로 이동
scrollTo(index)특정 슬라이드로 이동
canScrollPrev()이전 이동 가능 여부
canScrollNext()다음 이동 가능 여부
scrollSnapList()전체 스냅 포인트 목록
selectedScrollSnap()현재 선택된 스냅 인덱스

Events

EventDescription
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 텍스트 포함

권장 사항

  • ✅ 키보드 좌/우 화살표로 슬라이드 이동 지원
  • ✅ 자동 재생 시 일시정지 컨트롤 제공
  • ❌ 자동 재생만으로 콘텐츠를 제공하지 않음 (수동 이동 병행)

관련 컴포넌트

  • Card: 슬라이드 콘텐츠 컨테이너
  • Button: 커스텀 네비게이션 버튼
Last updated on