Carousel
이미지를 슬라이드 형태로 표시하고, 클릭 시 외부 콜백을 호출하는 캐러셀 컴포넌트
개요
이미지 목록을 좌우 슬라이드로 표시합니다. 화살표와 인디케이터로 탐색하며, 자동 재생(autoplay)을 지원합니다. 이미지를 클릭하면 onClickImage 콜백이 호출되어, 페이지 이동이나 이력 기록 등을 외부에서 처리할 수 있습니다.
주요 특징
- ✅ 단일/다중 슬라이드: 이미지가 2장 이상이면 화살표와 인디케이터를 표시
- ✅ 자동 재생: autoplay/delay로 자동 슬라이드
- ✅ 화살표 모드: always, hover, never 세 가지 표시 방식
- ✅ 클릭 콜백: clickable + onClickImage로 이미지 클릭 이벤트 위임
- ✅ 읽기 전용: readOnly 시 모든 인터랙션 비활성
- ✅ 슬라이드 이벤트: onChange로 현재/이전 인덱스와 현재 이미지 전달
기본 사용
images에 { id, src } 목록을 전달합니다. 1장이면 화살표/인디케이터가 표시되지 않습니다.
Preview
자동 재생 (Autoplay)
autoplay를 설정하면 지정된 delay(ms) 간격으로 자동으로 슬라이드가 전환됩니다. 사용자 인터랙션 시 일시 정지되고, 마우스를 떼면 다시 재생됩니다.
<Carousel images={images} autoplay delay={3000} height={240} />화살표 표시 방식 (arrow)
| 값 | 동작 |
|---|---|
always | 항상 표시 (기본) |
hover | 마우스를 올렸을 때만 표시 |
never | 화살표 숨김 (인디케이터만으로 탐색) |
<Carousel images={images} arrow="hover" />이미지 클릭 (onClickImage)
clickable=true(기본)이고 이미지에 url이 있으면 클릭 시 onClickImage 콜백이 호출됩니다. 콜백 데이터에는 클릭된 이미지 객체와 인덱스가 포함됩니다.
<Carousel
images={images}
onClickImage={(data) => {
// data.image — 클릭된 이미지 객체
// data.index — 슬라이드 인덱스
window.open(data.image.url, "_blank")
}}
/>읽기 전용 (readOnly)
readOnly 시 화살표, 인디케이터, 드래그, 클릭, 자동 재생이 모두 비활성화됩니다.
Preview
이미지 없음 (No-Image)
images가 빈 배열이면 no-image placeholder가 표시됩니다. noImageSrc를 지정하면 커스텀 이미지를 사용합니다.
Preview
API Reference
CarouselImage
| 필드 | Type | 필수 | Description |
|---|---|---|---|
id | string | ✅ | 슬라이드 key |
src | string | ✅ | 이미지 URL |
url | string | - | 클릭 시 이동할 링크 URL |
alt | string | - | 대체 텍스트 (접근성) |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
images | CarouselImage[] | [] | 표시할 이미지 목록 |
autoplay | boolean | false | 자동 재생 여부 |
delay | number | 4000 | 자동 재생 간격 (ms) |
arrow | "always" | "hover" | "never" | "always" | 화살표 표시 방식 |
indicator | boolean | true | 인디케이터 표시 여부 |
clickable | boolean | true | 이미지 클릭 시 onClickImage 호출 여부 |
readOnly | boolean | false | 읽기 전용 — 화살표/인디케이터 숨김, 드래그/클릭 비활성 |
height | string | number | 300 | 캐러셀 뷰포트 높이 (number → px) |
noImageSrc | string | - | 커스텀 no-image 이미지 URL |
visible | boolean | true | 표시 여부 (false → 렌더 안 함) |
className | string | - | 컨테이너 className |
style | CSSProperties | - | 인라인 스타일 |
ref | Ref<CarouselRef> | - | currentIndex/currentImage/scroll 제어 |
Events
| Event | Type | Description |
|---|---|---|
onClickImage | (data: CarouselClickData) => void | 이미지 클릭 시 호출 |
onChange | (data: CarouselChangeData) => void | 슬라이드 변경 시 호출 |
CarouselRef
| 멤버 | Type | Description |
|---|---|---|
currentIndex | number | 현재 슬라이드 인덱스 |
currentImage | CarouselImage | undefined | 현재 이미지 정보 |
scrollTo(index) | (index: number) => void | 지정 슬라이드로 이동 |
scrollNext() | () => void | 다음 슬라이드 |
scrollPrev() | () => void | 이전 슬라이드 |
element | HTMLDivElement | null | 컨테이너 DOM 요소 |
접근성
권장 사항
- ✅ 각 이미지에
alt텍스트를 제공하여 대체 텍스트를 노출 - ✅ 캐러셀 영역에
role="region",aria-roledescription="carousel"부여 (Foundation 기본) - ✅ 각 슬라이드에
role="group",aria-roledescription="slide"부여 (Foundation 기본) - ✅ 인디케이터에
aria-label과aria-current로 현재 슬라이드를 표시
관련 컴포넌트
- ImageView: 확대 보기를 지원하는 이미지 뷰어
- Foundation Carousel: 기본 캐러셀 컴포넌트
Last updated on