Carousel

이전·다음·직접 이동 제어로 연속된 슬라이드를 탐색합니다.

용법

순환 이동

마지막 슬라이드 다음에는 첫 슬라이드로, 첫 슬라이드 이전에는 마지막으로 이동합니다.

FoundationDesign tokens

One source of truth for color, type, and spacing.

<!-- Carousel / Wrapping -->
<script setup lang="ts">
import { CarouselRoot, CarouselTrack, CarouselSlide, CarouselPrevious, CarouselNext, CarouselPause, CarouselIndicatorGroup, CarouselIndicator } from '@sectile/vue/carousel'
const slides = ['foundation', 'adapters', 'frameworks']

</script>

<template>
  <CarouselRoot :slides="slides" default-value="foundation">
    <CarouselTrack>
      <CarouselSlide v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselSlide>
    </CarouselTrack>
    <CarouselPrevious>Previous</CarouselPrevious>
    <CarouselNext>Next</CarouselNext>
    <CarouselPause>Pause</CarouselPause>
    <CarouselIndicatorGroup>
      <CarouselIndicator v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselIndicator>
    </CarouselIndicatorGroup>
  </CarouselRoot>
</template>

범위 제한

입력값을 설정한 최솟값과 최댓값 범위 안에서 확정합니다.

FoundationDesign tokens

One source of truth for color, type, and spacing.

<!-- Carousel / Bounded -->
<script setup lang="ts">
import { CarouselRoot, CarouselTrack, CarouselSlide, CarouselPrevious, CarouselNext, CarouselPause, CarouselIndicatorGroup, CarouselIndicator } from '@sectile/vue/carousel'
const slides = ['foundation', 'adapters', 'frameworks']

</script>

<template>
  <CarouselRoot :slides="slides" default-value="foundation">
    <CarouselTrack>
      <CarouselSlide v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselSlide>
    </CarouselTrack>
    <CarouselPrevious>Previous</CarouselPrevious>
    <CarouselNext>Next</CarouselNext>
    <CarouselPause>Pause</CarouselPause>
    <CarouselIndicatorGroup>
      <CarouselIndicator v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselIndicator>
    </CarouselIndicatorGroup>
  </CarouselRoot>
</template>

일시 정지

자동 이동을 멈춘 상태에서도 직접 이전·다음 항목으로 이동할 수 있습니다.

FoundationDesign tokens

One source of truth for color, type, and spacing.

<!-- Carousel / Paused -->
<script setup lang="ts">
import { CarouselRoot, CarouselTrack, CarouselSlide, CarouselPrevious, CarouselNext, CarouselPause, CarouselIndicatorGroup, CarouselIndicator } from '@sectile/vue/carousel'
const slides = ['foundation', 'adapters', 'frameworks']

</script>

<template>
  <CarouselRoot :slides="slides" default-value="foundation">
    <CarouselTrack>
      <CarouselSlide v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselSlide>
    </CarouselTrack>
    <CarouselPrevious>Previous</CarouselPrevious>
    <CarouselNext>Next</CarouselNext>
    <CarouselPause>Pause</CarouselPause>
    <CarouselIndicatorGroup>
      <CarouselIndicator v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselIndicator>
    </CarouselIndicatorGroup>
  </CarouselRoot>
</template>

외부 상태 관리

현재 값은 부모가 관리하고, 허용된 변경을 컴포넌트에 다시 전달합니다.

FoundationDesign tokens

One source of truth for color, type, and spacing.

<!-- Carousel / Controlled -->
<script setup lang="ts">
import { CarouselRoot, CarouselTrack, CarouselSlide, CarouselPrevious, CarouselNext, CarouselPause, CarouselIndicatorGroup, CarouselIndicator } from '@sectile/vue/carousel'
const slides = ['foundation', 'adapters', 'frameworks']

</script>

<template>
  <CarouselRoot :slides="slides" default-value="foundation">
    <CarouselTrack>
      <CarouselSlide v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselSlide>
    </CarouselTrack>
    <CarouselPrevious>Previous</CarouselPrevious>
    <CarouselNext>Next</CarouselNext>
    <CarouselPause>Pause</CarouselPause>
    <CarouselIndicatorGroup>
      <CarouselIndicator v-for="slide in slides" :key="slide" :value="slide">
        {{ slide }}
      </CarouselIndicator>
    </CarouselIndicatorGroup>
  </CarouselRoot>
</template>

API

Vue 패키지: @sectile/vue/carousel

컴포넌트

CarouselRoot
CarouselViewport
CarouselTrack
CarouselIndicatorGroup
CarouselPrevious
CarouselNext
CarouselPause
CarouselSlide
CarouselIndicator

Props

`CarouselRootProps`

as: 타입PrimitiveAs기본값'section'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
autoplay: 타입boolean | CarouselAutoplayOptions기본값false
캐러셀이 자동으로 넘어갈지 여부입니다.
defaultPaused: 타입boolean기본값false
컴포넌트가 관리하는 초기 일시 정지 상태입니다.
defaultValue: 타입string | null기본값undefined
컴포넌트가 값을 관리할 때 사용할 초깃값입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
getIndicatorLabel: 타입(id: string, index: number, count: number) => string기본값undefined
각 캐러셀 표시기에 제공할 접근 가능한 이름을 만드는 함수입니다.
getSlideLabel: 타입(id: string, index: number, count: number) => string기본값undefined
각 캐러셀 슬라이드에 제공할 접근 가능한 이름을 만드는 함수입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.
modelValue: 타입string | null기본값undefined
부모가 상태를 관리할 때 사용할 현재 값입니다.
orientation: 타입'horizontal' | 'vertical'기본값'horizontal'
배치와 키보드 이동에 사용할 축입니다.
paused: 타입boolean기본값undefined
외부에서 제어하는 일시 정지 상태입니다.
policies: 타입CarouselPolicies기본값undefined
검증, 이동, 선택 동작을 조정하는 정책입니다.
slides: 타입readonly string[]기본값필수
캐러셀이 관리할 순서 있는 슬라이드 값입니다.

`CarouselPartProps`

as: 타입PrimitiveAs기본값파트별로 다름
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

슬롯

`CarouselRootSlotProps`

count: 타입number
컬렉션의 값 개수입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
index: 타입number | null
부모 컬렉션 안의 0부터 시작하는 위치입니다.
paused: 타입boolean
자동 갱신이 멈춘 상태인지 여부입니다.
value: 타입string | null
이 계약이 노출하는 현재 값입니다.

`CarouselSlideSlotProps`

active: 타입boolean
현재 활성 항목인지 여부입니다.
count: 타입number
컬렉션의 값 개수입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
index: 타입number | null
부모 컬렉션 안의 0부터 시작하는 위치입니다.
paused: 타입boolean
자동 갱신이 멈춘 상태인지 여부입니다.
value: 타입string
이 계약이 노출하는 현재 값입니다.

이벤트

`CarouselRoot`

announce: 페이로드string
보조 기술에 피드백을 알려야 할 때 발생합니다.
update:modelValue: 페이로드string | null
컴포넌트가 외부 제어 값의 변경을 요청할 때 발생합니다.
update:paused: 페이로드boolean
컴포넌트가 새 일시 정지 상태를 요청할 때 발생합니다.

기타 타입

`CarouselSlideLabelResolver`

type CarouselSlideLabelResolver = NonNullable<CarouselRootProps['getSlideLabel']>

`CarouselIndicatorLabelResolver`

type CarouselIndicatorLabelResolver = NonNullable<CarouselRootProps['getIndicatorLabel']>

`CarouselValueChangeHandler`

type CarouselValueChangeHandler = (value: string | null) => void

`CarouselPausedChangeHandler`

type CarouselPausedChangeHandler = (value: boolean) => void

`CarouselAnnounceHandler`

type CarouselAnnounceHandler = (value: string) => void

파트

공통 범위: [data-scope="carousel"]. 컴포넌트 내부로 스타일을 제한할 때 파트 선택자와 함께 사용합니다.

파트	선택자	역할	추가 속성
`root`	`[data-part="root"]`	컴포넌트 경계와 내부 파트를 묶습니다.	—
`viewport`	`[data-part="viewport"]`	현재 보이는 콘텐츠를 배치하고 경계를 정합니다.	—
`track`	`[data-part="track"]`	하나 이상의 핸들이 이동하는 측정 경로입니다.	—
`slide`	`[data-part="slide"]`	캐러셀 페이지 하나를 나타냅니다.	—
`previous`	`[data-part="previous"]`	이전 항목이나 페이지로 이동합니다.	—
`next`	`[data-part="next"]`	다음 항목이나 페이지로 이동합니다.	—
`pause`	`[data-part="pause"]`	자동 이동을 일시 정지하거나 다시 시작합니다.	—
`indicator-group`	`[data-part="indicator-group"]`	직접 위치 이동 조작부를 묶습니다.	—
`indicator`	`[data-part="indicator"]`	주요 콘텐츠와 나란히 상태나 위치를 표시합니다.	—

키보드 동작

키	동작
`Arrow Left` / `Arrow Right`	이전 또는 다음 슬라이드로 이동합니다.
`Home` / `End`	첫 번째 또는 마지막 슬라이드로 이동합니다.
`Enter` / `Space`	기본 이전·다음·일시 정지·표시 컨트롤을 실행합니다.

접근성

슬라이드, 이동 버튼, 일시 정지 버튼, 표시 항목을 각각 이름이 있고 조작 가능한 요소로 유지합니다.

관련 WAI-ARIA 패턴에서 호스트 접근성 규칙을 확인할 수 있습니다.

Carousel ​

용법 ​

순환 이동 ​

범위 제한 ​

일시 정지 ​

외부 상태 관리 ​

API ​

Props ​

CarouselRootProps ​

CarouselPartProps ​

슬롯 ​

CarouselRootSlotProps ​

CarouselSlideSlotProps ​

이벤트 ​

CarouselRoot ​

기타 타입 ​

CarouselSlideLabelResolver ​

CarouselIndicatorLabelResolver ​

CarouselValueChangeHandler ​

CarouselPausedChangeHandler ​

CarouselAnnounceHandler ​

파트 ​

키보드 동작 ​

접근성 ​

Carousel

용법

순환 이동

범위 제한

일시 정지

외부 상태 관리

API

Props

`CarouselRootProps`

`CarouselPartProps`

슬롯

`CarouselRootSlotProps`

`CarouselSlideSlotProps`

이벤트

`CarouselRoot`

기타 타입

`CarouselSlideLabelResolver`

`CarouselIndicatorLabelResolver`

`CarouselValueChangeHandler`

`CarouselPausedChangeHandler`

`CarouselAnnounceHandler`

파트

키보드 동작

접근성