Components/Media/Carousel
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/carousel
Carousel is a slideshow component that allows users to cycle through a set of content items, such as images or videos.
Carousel consists of a content area and controls that enable users to navigate within that area. Content area is an empty container that accepts any kind of components inside of it. Most commonly used with <Image/> or <Card/>.
Control the size of previous/next buttons using `controlsSize` prop. It supports 3 sizes:
 - `medium` (default) - use in all common cases.
 - `small` - use when the carousel is inside content widgets (cards or modals).
 - `tiny` - use in especially dense layouts.
Control the skin of the buttons with the `buttonSkin` prop. It supports 4 skins:
 - `standard` (default) - use when the buttons are on a light background.
 - `transparent` - use when they are on a dark colored background.
 - `inverted` - use when they are on a light gray background.
 - `light` - use when they are on a dark background.
`inverted` and `light` skins also serve as alternatives to `standard` skin on a light background (use them to give less emphasis on the buttons).
Control the position of the buttons with `controlsPosition` prop. It supports 4 options:
 - `sides` (default) - use it to display controls on the sides of the content.
 - `bottom` - use it to display controls underneath the content.
 - `overlay` - use it to display controls directly on top of the content to save horizontal space. Give more emphasis to the controls by dropping a shadow below them with `showControlsShadow` prop.
 - `none` - use it to hide controls in conjunction with autoplay.
Control how images are aligned inside of a carousel content area with `imagesPosition` prop.
First value controls the alignment on the X-axis (`left`, `center`, `right`), the second value on the Y-axis (`top`, `middle` or `bottom`). Default is center top. Position can also be specified in pixels or %.
Control how images are displayed when their dimensions do not match container size with `imagesFit` prop. It supports all default CSS object-fit values, but most commonly used are the following ones:
 - `contain` (default) - scaled to maintain its aspect ratio while fitting within the element's content box. Scaled until one axis is filled.
 - `cover` - sized to maintain its aspect ratio while filling the element's entire content box.
 - `fill` - sized to completely fill the box.
 - `none` - keeps original image dimensions.
 - `scale-down` - sized as if none or contain were specified, whichever would result in a smaller concrete object size.
Specify whether to display a single item at a time or few elements simultaneously using `variableWidth` prop. When set to `true`, child items will be stacked one after another horizontally.
Control whether pagination below the carousel is visible with `dots` prop.
Disable users from cycling through content items endlessly by setting `infinite` prop value to false. Control whether to display disabled start and end buttons at the end of the cycle or not show them at all with `controlsStartEnd` prop.
Switch between content items automatically with `autoplay` prop. When enabled, slides will change every 3 seconds.
Use `initialSlideIndex` prop to set the initial slide as the starting point.
Use Carousel to display a series of content.
Use Carousel to display a series of Marketing layouts.
| Name | Type | Default | Description |
|---|---|---|---|
afterChange | (currentSlide: number) => void | — | Index change callback. index => ... |
align | "center" | "end" | "start" | 'start' | Defines how slides align relative to the viewport. When set, this takes full control of slide positioning and startEndOffset is ignored. If neither align nor startEndOffset is provided, defaults to 'start'. |
animationDuration | number | — | Animation duration in milliseconds. |
autoplay | boolean | false | Specifies whether the carousel advances to the next slide automatically every 3 seconds. Autoplay pauses while the mouse is over the carousel. |
beforeChange | (currentSlide: number, nextSlide: number) => void | — | Index change callback. (oldIndex, newIndex) => ... |
buttonSkin | "standard" | "light" | "inverted" | "premium" | "transparent" | — | Sets the skin of the control (next / previous) buttons. |
children | ReactNode | — | Accepts any component as a child item. Most commonly used to display <Card/>, <Image/> or video files. |
controlsPosition | "overlay" | "none" | "bottom" | "sides" | — | Sets the control buttons' position. |
controlsSize | "small" | "tiny" | "medium" | "large" | — | Sets the control buttons' size. |
controlsStartEnd | "disabled" | "hidden" | — | Controls if the next / previous control buttons are visible, hidden or disabled at the start and end of the slideshow. |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in the tests. |
dots | boolean | — | Controls if the bottom dots are visible or hidden. |
gradient | boolean | false | Enables gradient on when controlsPosition set to overlay. |
gradientColor | string | white | Controls gradient color when controlsPosition set to overlay. |
images | CarouselImage[] | — | Defines an array of objects where each contains the src of an image (in <img src="your_src" />). |
imagesFit | "none" | "fill" | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "contain" | "cover" | "scale-down" | — | Sets the image's fit. |
imagesPosition | string | number | string & {} | — | Sets the image's position. |
infinite | boolean | — | Loops images endlessly. |
initialSlideIndex | number | — | Sets the slide to start a presentation with. |
ref | null | string | (instance: CarouselHandle | null) => void | RefObject<CarouselHandle> | — | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). |
showControlsShadow | boolean | — | Drops a shadow below the control buttons. |
slideSpacing | number | — | Number of pixels dividing between slides. |
slidesPerPage | number | { minSlideWidth: number; maxSlides?: number | undefined; } | — | Shows several slides side by side on one page. A number fixes the count; an object fits as many slides as the strip allows, each at least minSlideWidth px wide, up to maxSlides. Indices in the other props keep referring to slides, not pages. Turns off variableWidth, align, startEndOffset and slidingType for this instance. |
slidingType | number | "align-to-start" | "reveal-one" | "reveal-chunk" | — | Specifies how many slides advance per navigation action. |
startEndOffset | number | — | Number of pixels for showing "peeking" cards on the edges of the carousel. Adds visible offset at the start and end of the carousel to hint at more content. Only takes effect when align isn't explicitly set. If align is provided, this prop is ignored. Use one or the other, not both. |
variableWidth | boolean | — | Shows one slide at a time (default) or stacks one slide after another horizontally. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
isLoading | — |
getChildren | — |
getImages | — |
clickPrevious | — |
clickNext | — |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
click | Clicks on the component root element. |
base | Returns UniDriver for the base element. |
slidesPerPage prop that shows several slides side by side on one page, either a fixed count or as many as fit a minSlideWidth, and keeps slide shadows unclipped at the page edges. (#17015) — has visual changesLast updated: 22 October 2026