Carousel

Embla 기반의 모션과 스와이프를 지원하는 캐러셀입니다.

디지털 정부 서비스

정부24에서 다양한 민원 서비스를 한 번에 신청할 수 있습니다.

신청 진행 상황

마이페이지에서 진행 단계를 한눈에 확인하세요.

안내 사항

이용 안내와 도움말을 통해 빠르게 시작할 수 있습니다.

examples/krds/carousel-demo.tsx

import * as React from "react"

import { Card, CardContent } from "@/components/ui/card"

개요

Carousel 컴포넌트는 Embla Carousel 기반으로 동작하며, KRDS 포팅에서는 이전/다음 버튼과 항목 간격을 KRDS 컨트롤 톤에 맞춥니다.

설치

pnpm dlx shadcn@latest add https://krdscn.gwlee.kr/r/carousel.json

사용법

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"

<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

구성

다음 조합으로 Carousel:

Carousel
├── CarouselContent
│   ├── CarouselItem
│   └── CarouselItem
├── CarouselPrevious
└── CarouselNext

예제

크기

항목 크기는 <CarouselItem />에 basis 유틸리티 클래스를 지정해 조정합니다.

examples/krds/carousel-size.tsx

import * as React from "react"

import { Card, CardContent } from "@/components/ui/card"

// 캐러셀 너비의 33%입니다.
<Carousel>
  <CarouselContent>
    <CarouselItem className="basis-1/3">...</CarouselItem>
    <CarouselItem className="basis-1/3">...</CarouselItem>
    <CarouselItem className="basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>

// 작은 화면에서는 50%, 큰 화면에서는 33% 너비를 사용합니다.
<Carousel>
  <CarouselContent>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>

간격

항목 간격은 <CarouselItem />의 pl-[VALUE]와 <CarouselContent />의 음수 -ml-[VALUE]를 조합해 설정합니다.

examples/krds/carousel-spacing.tsx

import * as React from "react"

import { Card, CardContent } from "@/components/ui/card"

<Carousel>
  <CarouselContent className="-ml-4">
    <CarouselItem className="pl-4">...</CarouselItem>
    <CarouselItem className="pl-4">...</CarouselItem>
    <CarouselItem className="pl-4">...</CarouselItem>
  </CarouselContent>
</Carousel>

<Carousel>
  <CarouselContent className="-ml-2 md:-ml-4">
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
    <CarouselItem className="pl-2 md:pl-4">...</CarouselItem>
  </CarouselContent>
</Carousel>

방향

orientation prop으로 Carousel 방향을 설정합니다.

examples/krds/carousel-orientation.tsx

import * as React from "react"

import { Card, CardContent } from "@/components/ui/card"

<Carousel orientation="vertical | horizontal">
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
</Carousel>

옵션

opts prop으로 캐러셀 옵션을 전달할 수 있습니다. 자세한 내용은 Embla Carousel 문서를 참고하세요.

<Carousel
  opts={{
    align: "start",
    loop: true,
  }}
>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
</Carousel>

API

상태와 setApi prop을 사용해 캐러셀 API 인스턴스를 받을 수 있습니다.

Slide 0 of 0

examples/krds/carousel-api.tsx

"use client"

import * as React from "react"

import { type CarouselApi } from "@/components/ui/carousel"

export function Example() {
  const [api, setApi] = React.useState<CarouselApi>()
  const [current, setCurrent] = React.useState(0)
  const [count, setCount] = React.useState(0)

  React.useEffect(() => {
    if (!api) {
      return
    }

    setCount(api.scrollSnapList().length)
    setCurrent(api.selectedScrollSnap() + 1)

    api.on("select", () => {
      setCurrent(api.selectedScrollSnap() + 1)
    })
  }, [api])

  return (
    <Carousel setApi={setApi}>
      <CarouselContent>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
      </CarouselContent>
    </Carousel>
  )
}

이벤트

setApi에서 받은 api 인스턴스로 캐러셀 이벤트를 구독할 수 있습니다.

import { type CarouselApi } from "@/components/ui/carousel"

export function Example() {
  const [api, setApi] = React.useState<CarouselApi>()

  React.useEffect(() => {
    if (!api) {
      return
    }

    api.on("select", () => {
      // 선택 변경 시 필요한 작업을 실행합니다.
    })
  }, [api])

  return (
    <Carousel setApi={setApi}>
      <CarouselContent>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
        <CarouselItem>...</CarouselItem>
      </CarouselContent>
    </Carousel>
  )
}

이벤트 사용법은 Embla Carousel 문서를 참고하세요.

플러그인

plugins prop으로 캐러셀 플러그인을 추가할 수 있습니다.

import Autoplay from "embla-carousel-autoplay"

export function Example() {
  return (
    <Carousel
      plugins={[
        Autoplay({
          delay: 2000,
        }),
      ]}
    >
      // ...
    </Carousel>
  )
}

examples/krds/carousel-plugin.tsx

"use client"

import { Card, CardContent } from "@/components/ui/card"

RTL

RTL 지원을 활성화하려면 RTL 설정 가이드를 참고하세요.

examples/krds/carousel-rtl.tsx

"use client"

import {

RTL 언어로 캐러셀을 사용할 때는 텍스트 방향과 맞도록 opts의 direction 옵션을 설정합니다. 이렇게 해야 캐러셀이 올바른 방향으로 이동합니다.

<Carousel
  dir={dir}
  opts={{
    direction: dir,
  }}
>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious className="rtl:rotate-180" />
  <CarouselNext className="rtl:rotate-180" />
</Carousel>

direction 옵션은 "ltr" 또는 "rtl"을 받으며 dir prop 값과 일치해야 합니다. 이전/다음 버튼은 rtl:rotate-180 클래스로 방향을 맞출 수 있습니다.

API 참조

prop과 플러그인 정보는 Embla Carousel 문서를 참고하세요.

Card Chart