캐러셀 Carousel

캐러셀은 하나의 영역에서 여러 개의 콘텐츠를 순차적으로 번갈아 보여주는 컴포넌트이다. 한정된 공간에 여러 콘텐츠를 노출할 수 있으나 첫 번째 슬라이드 외에는 주목도가 크게 떨어지므로, 중요한 정보는 캐러셀에만 담지 않는 것이 좋다. 슬라이드는 기본 슬롯으로 전달하며 최상위 노드 하나가 슬라이드 한 장이 된다. 자동 재생 시에는 사용자가 즉시 정지할 수 있도록 재생/정지 버튼을 함께 노출한다.

KRDS 가이드

기본 (비주얼 배너형)

vue

<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <div style="background-color: #d8e4f2">
    <KrdsCarousel variant="visual" aria-label="주요 서비스 안내" more-href="#">
      <div v-for="index in 4" :key="index" class="in">
        <div class="text">
          <p class="tit">타이틀 영역 {{ index }}</p>
          <p class="txt">컨텐츠 영역 컨텐츠 영역 {{ index }}</p>
          <a href="#" class="krds-btn primary">버튼 영역</a>
        </div>
        <div class="im">
          <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
            <rect width="243" height="178" fill="#E6E8EA" />
          </svg>
        </div>
      </div>
    </KrdsCarousel>
  </div>
</template>

배너형

배너형은 인디케이터 안에 분수형 페이지네이션과 이전/다음·더 보기 버튼을 배치합니다.

서브타이틀 1
타이틀 1
서브타이틀 2
타이틀 2
서브타이틀 3
타이틀 3

vue

<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <KrdsCarousel variant="banner" aria-label="배너형 캐러셀 예제" more-href="#">
    <div v-for="index in 3" :key="index" class="in">
      <div class="text">
        <p class="cate">서브타이틀 {{ index }}</p>
        <p class="tit">타이틀 {{ index }}</p>
      </div>
      <div class="im">
        <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
          <rect width="243" height="178" fill="#E6E8EA" />
        </svg>
      </div>
    </div>
  </KrdsCarousel>
</template>

자동 재생

자동 재생 중에는 정지 버튼이 노출되며, 정지하면 재생 버튼으로 바뀝니다. 마우스 오버나 키보드 포커스가 캐러셀 안에 있는 동안에는 자동 재생이 멈춥니다.

서브타이틀 1
타이틀 1
서브타이틀 2
타이틀 2
서브타이틀 3
타이틀 3

vue

<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <KrdsCarousel variant="banner" aria-label="자동 재생 캐러셀 예제" autoplay :autoplay-delay="3000" more-href="#">
    <div v-for="index in 3" :key="index" class="in">
      <div class="text">
        <p class="cate">서브타이틀 {{ index }}</p>
        <p class="tit">타이틀 {{ index }}</p>
      </div>
      <div class="im">
        <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
          <rect width="243" height="178" fill="#E6E8EA" />
        </svg>
      </div>
    </div>
  </KrdsCarousel>
</template>

순환 없음

loop를 끄면 처음과 마지막 슬라이드에서 이전/다음 버튼이 비활성화됩니다.

vue

<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <div style="background-color: #d8e4f2">
    <KrdsCarousel variant="visual" aria-label="순환 없는 캐러셀 예제" :loop="false">
      <div v-for="index in 4" :key="index" class="in">
        <div class="text">
          <p class="tit">타이틀 영역 {{ index }}</p>
          <p class="txt">컨텐츠 영역 컨텐츠 영역 {{ index }}</p>
          <a href="#" class="krds-btn primary">버튼 영역</a>
        </div>
        <div class="im">
          <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
            <rect width="243" height="178" fill="#E6E8EA" />
          </svg>
        </div>
      </div>
    </KrdsCarousel>
  </div>
</template>

분수형 페이지네이션

페이지네이션 방식은 형태와 무관하게 pagination 속성으로 바꿀 수 있습니다.

vue

<script setup lang="ts">
  import { KrdsCarousel } from '@krds.ui/vue'
</script>

<template>
  <div style="background-color: #d8e4f2">
    <KrdsCarousel variant="visual" aria-label="분수형 페이지네이션 캐러셀 예제" pagination="fraction">
      <div v-for="index in 4" :key="index" class="in">
        <div class="text">
          <p class="tit">타이틀 영역 {{ index }}</p>
          <p class="txt">컨텐츠 영역 컨텐츠 영역 {{ index }}</p>
          <a href="#" class="krds-btn primary">버튼 영역</a>
        </div>
        <div class="im">
          <svg width="243" height="178" viewBox="0 0 243 178" fill="none" xmlns="http://www.w3.org/2000/svg" aria-label="예시">
            <rect width="243" height="178" fill="#E6E8EA" />
          </svg>
        </div>
      </div>
    </KrdsCarousel>
  </div>
</template>

KrdsCarousel

Props

이름	타입	기본값	설명
`id`	`string`	-	엘리먼트 ID
`ariaLabel`	`string`	`'캐러셀'`	캐러셀 영역 접근성 라벨
`variant`	`KrdsCarouselVariant`	`'visual'`	캐러셀 형태 (기본값: visual)
`activeIndex`	`number`	-	현재 슬라이드 인덱스 (v-model:activeIndex)
`loop`	`boolean`	`true`	처음/마지막 슬라이드에서 순환 이동 여부 (기본값: true)
`autoplay`	`boolean`	`false`	자동 재생 여부. true면 재생/정지 버튼을 노출하고 즉시 재생을 시작한다 (기본값: false)
`autoplayDelay`	`number`	`DEFAULT_AUTOPLAY_DELAY`	자동 재생 간격 (ms, 기본값: 2500)
`pauseOnHover`	`boolean`	`true`	마우스 오버 시 자동 재생 일시 정지 여부 (기본값: true). 포커스 진입 시에는 값과 무관하게 항상 정지한다
`speed`	`number`	`DEFAULT_SPEED`	슬라이드 전환 속도 (ms, 기본값: 400)
`spaceBetween`	`number`	-	슬라이드 사이 간격 (px, 기본값: visual 0 / banner 16)
`pagination`	`KrdsCarouselPaginationType`	-	페이지네이션 표시 방식 (기본값: visual bullets / banner fraction)
`navigation`	`boolean`	`true`	이전/다음 버튼 표시 여부 (기본값: true)
`moreHref`	`string`	-	더 보기 링크 URL. 지정하면 더 보기 버튼을 표시한다
`prevLabel`	`string`	`'이전'`	이전 버튼 라벨
`nextLabel`	`string`	`'다음'`	다음 버튼 라벨
`playLabel`	`string`	`'슬라이드 재생'`	재생 버튼 라벨
`stopLabel`	`string`	`'슬라이드 멈춤'`	정지 버튼 라벨
`moreLabel`	`string`	`'더 보기'`	더 보기 버튼 라벨

Events

이름	인자	설명
`change`	`[value: number]`	슬라이드가 바뀌었을 때 (새 순서)
`play`	`[]`	자동 재생을 시작했을 때
`update:activeIndex`	`[value: number]`	현재 슬라이드 순서가 바뀔 때 (v-model:active-index)
`stop`	`[]`	자동 재생을 멈췄을 때
`more-click`	`[event: MouseEvent]`	더 보기 버튼을 클릭했을 때

Slots

이름	설명
`default`	슬라이드 (자식 요소 하나가 한 장)

캐러셀 Carousel ​

기본 (비주얼 배너형) ​

배너형 ​

자동 재생 ​

순환 없음 ​

분수형 페이지네이션 ​

KrdsCarousel ​