Soon UI Design

Layout
Navigation
Input
Select
Display
Feedback

Carousel

이미지 슬라이드를 구현할 수 있는 컴포넌트입니다. 비활성 슬라이드의 내부 요소는 키보드 포커스 대상에서 제외됩니다.

import { Carousel } from 'sud-ui';

GitHub에서 소스코드 보기

사용할 때

이미지 슬라이드를 구현할 때

사용예제

Basic Usage

기본적인 사용 방법입니다.

import React from "react";
import { Carousel, Card, Avatar } from "sud-ui";

export default function Example() {
  const renderItems = Array.from({ length: 5 }, (_, index) => (
    <Card key={index} width="100%">
      <div className="flex justify-center items-center">
        <Avatar sample={index + 1} size="xl" />
      </div>
    </Card>
  ));

  return (
    <Carousel 
      items={renderItems}
      itemWidthRatio={0.8}
      itemCount={1}
      autoPlay={true}
      autoPlayInterval={3000}
      effectType="fade"
    />
  );
}

fade

slide

scale

stack

Effect Type

효과 타입을 설정합니다.

import React, { useState } from "react";
import { Carousel, Card, Avatar, Radio } from "sud-ui";

export default function Example() {
  const [effectType, setEffectType] = useState("fade");
  const effectTypeOptions = [
    { label: "fade", value: "fade" },
    { label: "slide", value: "slide" },
    { label: "scale", value: "scale" },
    { label: "stack", value: "stack" }
  ];

  const renderItems = Array.from({ length: 5 }, (_, index) => (
    <Card key={index} width="100%">
      <div className="flex justify-center items-center">
        <Avatar sample={index + 1} size="xl" />
      </div>
    </Card>
  ));

  return (
    <div className="flex flex-col gap-[20px] justify-center items-center">
      <Card style={{ width: "100%" }} shadow="none" colorType="sub">
        <div className="flex justify-center">
          <Radio.Group
            options={effectTypeOptions}
            direction="horizontal"
            value={effectType}
            onChange={setEffectType}
          />
        </div>
      </Card>
      <Carousel items={renderItems} effectType={effectType} />
    </div>
  );
}

Button Customization

버튼을 커스텀할 수 있습니다.

import React from "react";
import { Carousel, Card, Avatar } from "sud-ui";
import { TriangleLeft, TriangleRight } from "sud-icons";

export default function Example() {
  const renderItems = Array.from({ length: 5 }, (_, index) => (
    <Card key={index} width="100%">
      <div className="flex justify-center items-center">
        <Avatar sample={index + 1} size="xl" />
      </div>
    </Card>
  ));

  return (
    <Carousel 
      items={renderItems}
      leftBtnIcon={<TriangleLeft size={30} />}
      rightBtnIcon={<TriangleRight size={30} />}
    />
  );
}

현재 슬라이드: 1/5

Interactive

onChange 함수와 currentIndex를 사용한 상호작용 예제입니다.

import React, { useState } from "react";
import { Carousel, Card, Avatar, Button, Typography, toast } from "sud-ui";

export default function Example() {
  const [currentIndex, setCurrentIndex] = useState(0);
  
  const renderItems = Array.from({ length: 5 }, (_, index) => (
    <Card key={index} width="100%">
      <div className="flex justify-center items-center">
        <Avatar sample={index + 1} size="xl" />
      </div>
    </Card>
  ));

  return (
    <div className="flex flex-col gap-[20px] justify-center items-center">
      <div className="flex gap-[10px] items-center">
        <Button
          onClick={() => setCurrentIndex((currentIndex - 1 + 5) % 5)}
          colorType="primary"
        >
          이전
        </Button>
        <Typography suite="B">
          현재 슬라이드: {currentIndex + 1}/5
        </Typography>
        <Button
          onClick={() => setCurrentIndex((currentIndex + 1) % 5)}
          colorType="primary"
        >
          다음
        </Button>
      </div>
      <Carousel
        items={renderItems}
        currentIndex={currentIndex}
        onChange={(index) => {
          setCurrentIndex(index);
          toast.success(`슬라이드 ${index + 1}로 이동했습니다!`);
        }}
      />
    </div>
  );
}

Autoplay

자동 재생 여부를 설정합니다. 기본값은 false입니다.

import React from "react";
import { Carousel, Card, Avatar } from "sud-ui";

export default function Example() {
  const renderItems = Array.from({ length: 5 }, (_, index) => (
    <Card key={index} width="100%">
      <div className="flex justify-center items-center">
        <Avatar sample={index + 1} size="xl" />
      </div>
    </Card>
  ));

  return (
    <Carousel 
      items={renderItems}
      autoPlay={true}
      autoPlayInterval={1000}  // 1초마다 자동 재생
    />
  );
}

Effect Type-Overlap

효과 타입 중 오버랩 효과입니다. 해당 효과는 itemCount, itemWidthRatio, scaleRatio, opacityRatio 옵션을 사용하여 오버랩 효과를 구현합니다.

import React from "react";
import { Carousel, Card, Avatar } from "sud-ui";

export default function Example() {
  const renderItems = Array.from({ length: 5 }, (_, index) => (
    <div className="flex justify-center items-center">
      <Card key={index} width="100%">
        <div className="flex justify-center items-center">
          <Avatar sample={index + 1} size="xl" />
        </div>
      </Card>
    </div>
  ));

  return (
    <Carousel 
      items={renderItems}
      effectType="overlap"
      itemCount={5}
      itemWidthRatio={0.4}
      scaleRatio={0.2}
      opacityRatio={0.3}
    />
  );
}

Drag

드래그로 슬라이드 넘기기 활성화 여부

import React from "react";
import { Carousel, Card, Avatar } from "sud-ui";

export default function Example() {
  const renderItems = Array.from({ length: 5 }, (_, index) => (
    <Card key={index} width="100%">
      <div className="flex justify-center items-center">
        <Avatar sample={index + 1} size="xl" />
      </div>
    </Card>
  ));

  return (
    <Carousel items={renderItems} drag={false} />
  );
}

사용 방법

컴포넌트의 props를 설정하는 방법입니다.

items

캐러셀에 표시할 아이템 배열

ReactNode[]

[]

itemWidthRatio

아이템의 너비 비율 (0~1)

number

0.8

itemCount

한 번에 표시할 아이템 수

number

itemGap

슬라이드 항목 사이의 간격

number

overlapOffsetRatio

overlap 효과에서 인접 항목이 이동하는 비율

number

0.55

autoPlay

자동 재생 여부

boolean

false

autoPlayInterval

자동 재생 간격 (ms)

number

3000

scaleRatio

아이템 크기 변화 비율

number

0.2

opacityRatio

아이템 투명도 변화 비율

number

0.1

width

캐러셀의 너비

string | number

100%

height

캐러셀의 높이

string | number

auto

className

추가 클래스명

string

drag

드래그로 슬라이드 넘기기 활성화 여부

boolean

true

style

추가 스타일

CSSProperties

{}

navBtn

네비게이션 버튼 표시 여부

boolean

true

leftBtnIcon

왼쪽 버튼 아이콘

ReactNode

rightBtnIcon

오른쪽 버튼 아이콘

ReactNode

effectType

전환 효과 타입

overlap

fade

slide

scale

stack

fade

onChange

슬라이드 변경 시 호출되는 콜백 함수

(index: number) => void

currentIndex

현재 슬라이드 인덱스 (외부 제어)

number

개인정보 처리방침

서비스 약관