Overview
Go Headless

Changelog

Wix Design System (WDS)
Introduction
About Wix Design System
Get started developing
Get started designing
Theming
Wix Design System AI

Guidelines
Themes
Interaction & Behavior
Guidelines
Localization

Patterns
Patterns Overview
Table Pattern
Grid Switch Pattern
Grid Pattern

Foundations
Tokens and Theming basics
Icon Theming

Contributing
AI-Assisted Development
Component Structure
Contributing to Wix Design System
Creating a New Component
Creating a Pull Request
Deprecating a Component
Documenting
Fixing a Bug
Test Drivers
Contributing Tokens
Token Migration Guidelines
Updating Props
Writing Tests

Components
Actions
Animations
Charts
Feedback
Form
Layout
Lists
Mechanisms
Media
AudioPlayer Component
Avatar Component
AvatarGroup Component
BrowserPreviewWidget
Carousel Component
CodeSnippet Component
Image Component
ImageViewer Component
MediaOverlay Component
Navigation
Overlays
Panels
Typography
In This Article

  1. Overview
  2. Code
  3. Testkit
  4. Changelog

Carousel

Components/Media/Carousel

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/carousel

Overview

Copy

Carousel is a slideshow component that allows users to cycle through a set of content items, such as images or videos.

Do

  • Use it to browse through visual content entities, such as images or videos.
  • Use it to display one or several items at a time.

Don't

  • Don't turn on autoplay for content that users need time to read.
  • Don't put essential information only in later slides, since users might not reach them.

Feature examples

Structure

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/>.

Copy

Size

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.

Copy

Button Skin

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).

Copy

Button Position

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.

Copy

Image Position

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 %.

Copy

Images Fit

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.

Copy

Variable width

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.

Copy

Dots

Control whether pagination below the carousel is visible with `dots` prop.

Copy

Infinite

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.

Copy

Autoplay

Switch between content items automatically with `autoplay` prop. When enabled, slides will change every 3 seconds.

Copy

Initial slide

Use `initialSlideIndex` prop to set the initial slide as the starting point.

Copy

Common use case examples

Image slideshow

Use Carousel to display a series of content.

Copy

Marketing layout

Use Carousel to display a series of Marketing layouts.

Copy

Code

Copy

Props

NameTypeDefaultDescription
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'.
animationDurationnumber—Animation duration in milliseconds.
autoplaybooleanfalseSpecifies 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.
childrenReactNode—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.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
dotsboolean—Controls if the bottom dots are visible or hidden.
gradientbooleanfalseEnables gradient on when controlsPosition set to overlay.
gradientColorstringwhiteControls gradient color when controlsPosition set to overlay.
imagesCarouselImage[]—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.
imagesPositionstring | number | string & {}—Sets the image's position.
infiniteboolean—Loops images endlessly.
initialSlideIndexnumber—Sets the slide to start a presentation with.
refnull | 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).
showControlsShadowboolean—Drops a shadow below the control buttons.
slideSpacingnumber—Number of pixels dividing between slides.
slidesPerPagenumber | { 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.
slidingTypenumber | "align-to-start" | "reveal-one" | "reveal-chunk"—Specifies how many slides advance per navigation action.
startEndOffsetnumber—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.
variableWidthboolean—Shows one slide at a time (default) or stacks one slide after another horizontally.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
isLoading—
getChildren—
getImages—
clickPrevious—
clickNext—
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.337.0 (2026-10-14) — maintenance release, no component-specific changes
  • 1.331.0 (2026-10-01) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — feat: add a 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 changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.313.1 (2026-08-18) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.299.0 (2026-07-17) — maintenance release, no component-specific changes
  • 1.295.0 (2026-07-03) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.270.0 (2026-04-20) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.257.0 (2026-02-19) — breaking: merge CarouselWIP into Carousel (#15862) — has visual changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.220.0 (2025-09-29) — breaking: dots & shadows for E3 (#15320)
  • 1.217.1 (2025-09-09) — fix: prev & next width (#15289)
  • 1.216.0 (2025-09-01) — fix: previous button placement (#15260)
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.205.0 (2025-07-15) — maintenance release, no component-specific changes
  • 1.187.0 (2025-05-07) — maintenance release, no component-specific changes
  • 1.181.0 (2025-04-18) — fix: arrows now aligned in the middle when dots are hidden (#14755)
  • 1.169.0 (2025-03-10) — maintenance release, no component-specific changes
  • 1.166.0 (2025-03-04) — feat: gradient & gradientColor (#14569)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.110.0 (2024-06-20) — fix: workaround for react-slick bug (#13859)
  • 1.109.1 (2024-06-11) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.98.0 (2024-03-15) — fix: add missing TS children prop type (#13483)
  • 1.94.0 (2024-02-14) — fix: autoplay interval increased from 2s to 3s (#13312)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?