Carousel

Carousel is a component that displays multiple elements like a slideshow.

Import

pnpm add @yamada-ui/carousel

Copied!

@yamada-ui/carousel is not included in @yamada-ui/react, so it needs to be installed separately.

import {
  Carousel,
  CarouselSlide,
  CarouselControlNext,
  CarouselControlPrev,
  CarouselIndicators,
} from "@yamada-ui/carousel"

Copied!

Carousel: A wrapper component that controls the child elements (CarouselSlide).
CarouselSlide: A component that displays a slide.
CarouselControlNext: A component for the button that shows the next slide.
CarouselControlPrev: A component for the button that shows the previous slide.
CarouselIndicators: A component that displays the number of slides and the current slide position.

CarouselControlNext, CarouselControlPrev, and CarouselIndicators can be omitted.

Usage

Carousel internally uses embla-carousel-react.

Editable example

<Carousel>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Specify the size

Editable example

const sizeMap = ["sm", "md", "lg", "xl"]
return (
  <VStack>
    {sizeMap.map((size) => (
      <Carousel key={size} size={size}>
        <CarouselSlide as={Center} bg="primary">
          1
        </CarouselSlide>
        <CarouselSlide as={Center} bg="secondary">
          2
        </CarouselSlide>
        <CarouselSlide as={Center} bg="warning">
          3
        </CarouselSlide>
        <CarouselSlide as={Center} bg="danger">
          4
        </CarouselSlide>
      </Carousel>
    ))}
  </VStack>
)

Copied!

Change the direction

To change the direction, set orientation to horizontal or vertical. By default, horizontal is set.

Editable example

<VStack>
  <Carousel orientation="horizontal">
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>

  <Carousel orientation="vertical">
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>
</VStack>

Copied!

Select the default slide

To select the default slide, set defaultIndex to the index.

Editable example

<Carousel defaultIndex={1}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Adjust the space between slides

To adjust the space between slides, set gap to a string or a number. By default, 1rem is set.

Editable example

<Carousel gap={0}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Change the duration of slide transition

To change the duration of slide transition, set duration to a number. By default, 25 is set.

Editable example

<Carousel duration={60}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Change the size of the slides

To change the size of the slides, set slideSize to a string or a number. By default, 100% is set.

If you want to change the size of individual slides, set the value to size of CarouselSlide.

Editable example

<Carousel slideSize="50%">
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary" size="100%">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Change the alignment of the slides

To change the alignment of the slides, set align to start, center, end, or a number. By default, center is set.

Editable example

<VStack>
  <Carousel slideSize="50%" align="center">
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>

  <Carousel slideSize="50%" align="start">
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>

  <Carousel slideSize="50%" align="end">
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>
</VStack>

Copied!

Change the number of slides to scroll

To change the number of slides to scroll, set slidesToScroll to a number. By default, 1 is set.

Editable example

<Carousel slideSize="33.3%" slidesToScroll={3} loop={false}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
  <CarouselSlide as={Center} bg="primary">
    5
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    6
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    7
  </CarouselSlide>
  <CarouselSlide as={Center} bg="primary">
    8
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    9
  </CarouselSlide>
</Carousel>

Copied!

Use autoplay

To use autoplay, set autoplay to true.

Editable example

<Carousel autoplay>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Change the autoplay interval

To change the autoplay interval, set delay to a number (milliseconds). By default, 4000 is set.

Editable example

<Carousel autoplay delay={1000}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Do not stop autoplay on mouse enter

By default, autoplay stops when the element is hovered over. To prevent this, set stopMouseEnterAutoplay to false.

Editable example

<Carousel autoplay stopMouseEnterAutoplay={false}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Use drag-free

By setting dragFree to true, you can freely drag the slides.

Editable example

<Carousel dragFree>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Disable looping

To disable looping, set loop to false.

Editable example

<Carousel loop={false}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Disable dragging

To disable dragging, set draggable to false.

Editable example

<Carousel draggable={false}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Disable control buttons

To disable control buttons, set withControls to false.

Editable example

<Carousel withControls={false}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Customize control buttons

To customize control buttons, set props to controlProps or controlPrevProps, or use CarouselControlPrev or CarouselControlNext.

Editable example

<VStack>
  <Carousel controlProps={{ icon: <GhostIcon /> }}>
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>

  <Carousel controlPrevProps={{ icon: <ArrowLeftIcon /> }}>
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>

  <Carousel controlNextProps={{ icon: <ArrowRightIcon /> }}>
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>

  <Carousel>
    <CarouselControlPrev icon={<ArrowLeftIcon />} />
    <CarouselControlNext icon={<ArrowRightIcon />} />

    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>
</VStack>

Copied!

Disable indicators

To disable indicators, set withIndicators to false.

Editable example

<Carousel withIndicators={false}>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Customize indicators

To customize indicators, set props to indicatorsProps, or use CarouselIndicators.

Editable example

<VStack>
  <Carousel
    indicatorsProps={{
      bottom: "8",
      component: ({ isSelected }) => (
        <GhostIcon
          color={isSelected ? "whiteAlpha.700" : "whiteAlpha.400"}
          cursor="pointer"
        />
      ),
    }}
  >
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>

  <Carousel>
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>

    <CarouselIndicators
      sx={{
        "& > *": {
          w: "4",
          _selected: { w: "12" },
          transitionProperty: "width",
          transitionDuration: "slower",
        },
      }}
    />
  </Carousel>
</VStack>

Copied!

Handle Events

If you want to handle events such as user drag, use watchDrag.

Editable example

<Carousel
  watchDrag={(methods, ev) => {
    console.log("drag", methods, ev)

    return true
  }}
  watchResize={(methods, entries) => {
    console.log("resized", methods, entries)

    return true
  }}
  watchSlides={(methods, mutations) => {
    console.log("slides updated", methods, mutations)

    return true
  }}
>
  <CarouselSlide as={Center} bg="primary">
    1
  </CarouselSlide>
  <CarouselSlide as={Center} bg="secondary">
    2
  </CarouselSlide>
  <CarouselSlide as={Center} bg="warning">
    3
  </CarouselSlide>
  <CarouselSlide as={Center} bg="danger">
    4
  </CarouselSlide>
</Carousel>

Copied!

Control

Editable example

const [index, onChange] = useState<number>(0)

return (
  <Carousel draggable={false} index={index} onChange={onChange}>
    <CarouselSlide as={Center} bg="primary">
      1
    </CarouselSlide>
    <CarouselSlide as={Center} bg="secondary">
      2
    </CarouselSlide>
    <CarouselSlide as={Center} bg="warning">
      3
    </CarouselSlide>
    <CarouselSlide as={Center} bg="danger">
      4
    </CarouselSlide>
  </Carousel>
)

Copied!

You can access the current scroll amount using onScrollProgress.

Editable example

const [value, onScrollProgress] = useState<number>(0)

return (
  <>
    <Carousel loop={false} dragFree onScrollProgress={onScrollProgress}>
      <CarouselSlide as={Center} bg="primary">
        1
      </CarouselSlide>
      <CarouselSlide as={Center} bg="secondary">
        2
      </CarouselSlide>
      <CarouselSlide as={Center} bg="warning">
        3
      </CarouselSlide>
      <CarouselSlide as={Center} bg="danger">
        4
      </CarouselSlide>
    </Carousel>

    <Progress value={value} colorScheme="gray" />
  </>
)

Copied!

Edit this page on GitHub

PreviousRadialChart NextReorder