신규 가입 혜택
이벤트지금 가입하면 첫 주문 20% 할인 쿠폰을 드립니다.
Carousel
Swiper 라이브러리 기반 Next.js Client Component입니다. 표준 swiper · swiper-wrapper · swiper-slide 마크업을 사용하며, 슬라이드 콘텐츠는 card · tag · btn 등 기존 컴포넌트를 조합합니다.
기본
Swiper Default 데모와 동일한 내비게이션·페이지네이션 구성입니다. 터치·스와이프·키보드·grab cursor를 기본 지원합니다.
페이드
effect="fade" prop으로 페이드 전환을 적용합니다.
자동 재생
autoplay prop으로 자동 재생과 재생·정지 버튼을 제공합니다. 기본 슬라이드 전환과 effect="fade" 페이드 전환을 모두 지원합니다.
슬라이드
기본 슬라이드 전환. effect prop을 생략합니다.
페이드
effect="fade" prop으로 페이드 전환을 적용합니다.
무한 루프
loop prop으로 슬라이드를 순환합니다.
슬라이드 per view
slidesPerView="auto"로 여러 카드가 동시에 보입니다.
간격
spaceBetween prop으로 슬라이드 간격을 지정합니다.
페이지네이션
화살표 없이 도트만 사용합니다.
분수 페이지네이션
pagination="fraction" prop으로 현재/전체 슬라이드 번호를 표시합니다.
프로그레스 페이지네이션
pagination="progressbar" prop으로 진행률 바를 표시합니다.
커스텀 페이지네이션
pagination="custom" prop으로 번호 불릿을 표시합니다.
그리드
gridRows prop으로 다행 그리드 레이아웃을 구성합니다. slidesPerGroup으로 1장씩 또는 한 화면(그룹) 단위 이동을 선택할 수 있습니다.
1장씩 이동
slidesPerGroup 생략(기본 1) — 화살표·스와이프 시 한 칸씩 이동합니다.
그룹 이동
slidesPerGroup={6} — 한 화면(2행 × 3열) 단위로 페이지처럼 이동합니다.
커버플로우
effect="coverflow" prop으로 3D 커버플로우 효과를 적용합니다. 활성 슬라이드는 가운데 정렬되며, coverflowSides={1}로 좌·우 1개씩 peek합니다.
커버플로우 · 축소
coverflowStyle="rise"로 측면만 축소합니다. 슬라이드 크기는 coverflowSides와 관계없이 동일하며, 좌·우 노출(1 · 1.5 · 2)은 간격으로 조절합니다.
좌우 1개씩
coverflowSides={1} — 슬라이드 크기 기준. 좌·우에 1개씩.
좌우 약 1.5개 (기본)
coverflowSides={1.5} — 크기는 1과 동일, 간격으로 좌·우 약 1.5개 peek.
좌우 2개씩
coverflowSides={2} — 크기는 1과 동일, 간격으로 좌·우 2개씩 peek.
썸네일 갤러리
메인 캐러셀과 썸네일 캐러셀을 thumbs · onSwiper로 양방향 연동합니다. 하단 썸네일은 탭 네비처럼 동작합니다.
API · Props
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
ariaLabel | string | — | 캐러셀 접근성 라벨 (필수) |
demo | boolean | true | carousel_demo 클래스 적용 |
multi | boolean | false | carousel_multi — slides per view auto 레이아웃 |
dotsOutside | boolean | false | carousel_dots-outside — 페이지네이션을 뷰포트 밖에 배치 |
autoplayToggle | boolean | false | 재생·정지 버튼 표시. autoplay가 활성이면 기본으로 함께 표시됩니다. |
effect | 'fade' | 'coverflow' | — | 전환 효과. 생략 시 슬라이드 |
autoplay | boolean | false | 자동 재생. 재생·정지 버튼이 함께 표시됩니다. |
delay | number | 4000 | 자동 재생 간격(ms) |
loop | boolean | false | 무한 루프 |
initialSlide | number | 0 | 시작 슬라이드 인덱스 (0부터). 커버플로우·축소 기본은 첫 슬라이드(0) |
slidesPerView | number | 'auto' | 1 | 동시 표시 슬라이드 수 |
slidesPerGroup | number | 1 | 한 번에 이동하는 슬라이드 수. 그리드에서는 slidesPerView × gridRows(예: 3×2=6)로 페이지 단위 이동 |
spaceBetween | number | 0 | 슬라이드 간격(px). Swiper spaceBetween에 전달. multi·grid·coverflow와 함께 사용 |
centered | boolean | false | 활성 슬라이드 중앙 정렬. coverflow일 때 자동 적용 |
pagination | boolean | 'fraction' | 'progressbar' | 'custom' | true | 페이지네이션 표시. fraction·progressbar·custom(번호) 지원 |
navigation | boolean | true | 이전·다음 화살표 표시 |
gridRows | number | 1 | Grid 행 수. 2 이상이면 Grid 레이아웃 |
gridFill | 'row' | 'column' | 'row' | Grid 채움 방향 |
coverflowStyle | 'tilt' | 'rise' | 'tilt' | coverflow 스타일. tilt는 좌우 기울임, rise는 기울임 없이 측면 슬라이드만 축소 |
coverflowSides | 1 | 1.5 | 2 | 'auto' | 1.5 | 활성 기준 좌·우 노출 수. 슬라이드 크기는 항상 1 기준(동일). 1.5·2는 간격을 좁혀 peek만 늘림 |
coverflowEffect | object | — | coverflow/rise 효과 세부 옵션. 지정 시 스타일 프리셋에 병합 |
thumbs | Swiper | — | Thumbs로 연결할 썸네일 Swiper 인스턴스 |
thumbsControl | boolean | false | 썸네일 컨트롤 캐러셀. 탭 네비처럼 시작 좌측 정렬, 중간은 활성 가운데, 끝은 우측(잘림 없이 클램프) |
watchSlidesProgress | boolean | false | 슬라이드 진행 상태 감시 (Thumbs 연동용) |
freeMode | boolean | false | Free mode. thumbsControl과 함께 쓰면 가운데 스냅이 약해질 수 있음 |
onSwiper | (swiper: Swiper) => void | — | Swiper 인스턴스 콜백 (썸네일 연결 등) |
children | ReactNode | — | CarouselSlide 자식 슬라이드 |
className | string | — | 루트 요소 추가 클래스 |
ripple | boolean | true | 클릭 파장(ripple). true 시 자식 클릭 표면에 data-ripple · false 시 data-no-ripple으로 하위 전체 비활성 |
API · Children
| Prop / Children | 설명 |
|---|---|
children | CarouselSlide 자식 슬라이드 |
슬라이드 콘텐츠는 CarouselSlide로 감싸 card 등 기존 컴포넌트를 배치합니다.
클래스 · 속성
React 컴포넌트가 렌더하는 OOCSS 클래스입니다. HTML 마크업으로 직접 작성할 때 동일하게 조합합니다.
| 클래스 | 설명 |
|---|---|
carousel | 루트 래퍼 (디자인 토큰·레이아웃) |
carousel_demo | 데모 영역 전체 너비 |
carousel_multi | slides per view auto 레이아웃 |
carousel_toggle | 자동 재생 재생·정지 버튼 |
carousel_dots-outside | 페이지네이션을 뷰포트 밖에 배치 |
carousel_coverflow | coverflow 효과 레이아웃 |
carousel_coverflow-rise | coverflow rise — 기울임 없이 측면 슬라이드 축소 |
carousel_coverflow-sides-1 · sides-15 · sides-2 | coverflow 좌·우 노출 개수 (1 / 1.5 / 2) |
carousel_grid | Grid 다행 레이아웃 |
carousel_gallery | 메인+썸네일 갤러리 래퍼 |
carousel_thumbs | 썸네일 컨트롤 캐러셀 |
carousel_pagination-progress | progressbar 페이지네이션 |
carousel_pagination-custom | 번호 커스텀 페이지네이션 |
swiper · swiper-wrapper · swiper-slide | Swiper 표준 구조 |
data-swiper | HTML 마크업 Swiper 초기화 대상 |
data-swiper-effect | HTML 전환 효과 (fade · coverflow) |
data-swiper-coverflow-style | HTML coverflow 스타일 (tilt · rise) |
data-swiper-coverflow-sides | HTML coverflow 좌·우 노출 수 (1 · 1.5 · 2) |
data-swiper-autoplay · data-swiper-delay | HTML 자동 재생 |
data-swiper-loop | HTML 무한 루프 |
data-swiper-initial-slide | HTML 시작 슬라이드 인덱스 |
data-swiper-slides-per-view · data-swiper-space-between | HTML 슬라이드 레이아웃 |
data-swiper-slides-per-group | HTML 한 번에 이동하는 슬라이드 수 (그룹 이동) |
data-swiper-centered | HTML 중앙 정렬 |
data-swiper-pagination | HTML 페이지네이션 유형 (fraction · progressbar · custom) |
data-swiper-grid-rows · data-swiper-grid-fill | HTML Grid 행·채움 방향 |
data-swiper-thumbs | HTML Thumbs 대상 셀렉터 |
is-autoplay-paused | 사용자가 정지한 자동 재생 상태 |
data-ripple | 클릭 파장 활성. data-ripple="surface"는 절대 위치 보조 버튼용 |
data-ripple="false" | 해당 요소 ripple 비활성 |
data-no-ripple | 하위 전체 ripple 비활성 |
디자인 토큰
| 토큰 | 기본값 | 설명 |
|---|---|---|
--carousel-height · --carousel-radius · --carousel-bg | 16rem · var(--radius-lg) · var(--color-surface-raised) | 슬라이드 영역(md) |
--carousel-font-size · --carousel-transition | var(--text-size-sm) · 0.35s ease | 타이포·전환 |
--carousel-nav-size · --carousel-nav-icon-size · --carousel-nav-offset | 2.25rem · 0.875rem · var(--space-md) | 이전/다음 버튼(md) |
--carousel-nav-bg · --carousel-nav-color | var(--color-surface) · var(--color-text) | 네비게이션 색 |
--carousel-dot-gap · --carousel-dot-size · --carousel-dot-size-active | 0.375rem · 0.5rem · 1.25rem | 인디케이터 점 |
--carousel-dot-bg · --carousel-dot-bg-active | var(--color-border) · var(--color-accent) | 점 색상 |
--carousel-dots-padding-y · --carousel-dots-padding-x | var(--space-md) · var(--space-md) | 인디케이터 영역 패딩 |
--carousel-toggle-size · --carousel-toggle-icon-size | 2rem · 1rem | 재생/일시정지 토글 |
--carousel-height-sm · --carousel-nav-size-sm | 11rem · 1.875rem | sm 크기 |
--carousel-height-lg · --carousel-nav-size-lg | 20rem · 2.75rem | lg 크기 |