Carousel

A slideshow component for cycling through elements.

import * as React from 'react';
import { Carousel } from '@itwin/itwinui-react';

export default () => {
  const gradients = [
    { from: '#cc2b5e', to: '#753a88' },
    { from: '#00467f', to: '#a5cc82' },
    { from: '#2193b0', to: '#6dd5ed' },
    { from: '#ffe000', to: '#799f0c' },
    { from: '#e65c00', to: '#f9d423' },
    { from: '#1488cc', to: '#2b32b2' },
    { from: '#bbd2c5', to: '#536976' },
    { from: '#9796f0', to: '#fbc7d4' },
    { from: '#b79891', to: '#94716b' },
    { from: '#acb6e5', to: '#86fde8' },
  ];

  return (
    <Carousel className='demo-carousel'>
      <Carousel.Navigation />
      <Carousel.Slider>
        {gradients.map(({ from, to }, index) => (
          <Carousel.Slide key={index}>
            <div
              className='demo-carousel-gradient'
              style={{
                background: `linear-gradient(to right, ${from}, ${to})`,
              }}
            >
              <div className='demo-carousel-number'>{index + 1}</div>
            </div>
          </Carousel.Slide>
        ))}
      </Carousel.Slider>
    </Carousel>
  );
};

The Carousel component consists of a set of slides, normally displayed one at a time. A navigation section is located below the slides, consisting of “dots” and “previous”/“next” buttons, used for changing slides.

Usage

The Carousel component is made up of customizable subcomponents. Here’s what the basic usage looks like:

<Carousel>
  <Carousel.Navigation />
  <Carousel.Slider>
    <Carousel.Slide>…</Carousel.Slide>
    <Carousel.Slide>…</Carousel.Slide>
    <Carousel.Slide>…</Carousel.Slide>
  </Carousel.Slider>
</Carousel>

Controlled State

By default, the carousel maintains its own state. But it can also be controlled externally using activeSlideIndex and onSlideChange.

import * as React from 'react';
import { Carousel } from '@itwin/itwinui-react';

export default () => {
  const gradients = [
    { from: '#cc2b5e', to: '#753a88' },
    { from: '#00467f', to: '#a5cc82' },
    { from: '#2193b0', to: '#6dd5ed' },
    { from: '#ffe000', to: '#799f0c' },
    { from: '#e65c00', to: '#f9d423' },
    { from: '#1488cc', to: '#2b32b2' },
    { from: '#bbd2c5', to: '#536976' },
    { from: '#9796f0', to: '#fbc7d4' },
    { from: '#b79891', to: '#94716b' },
    { from: '#acb6e5', to: '#86fde8' },
  ];

  const [currentIndex, setCurrentIndex] = React.useState(5);

  return (
    <Carousel
      activeSlideIndex={currentIndex}
      onSlideChange={(index) => setCurrentIndex(index)}
      className='demo-carousel'
    >
      <Carousel.Navigation />
      <Carousel.Slider>
        {gradients.map(({ from, to }, index) => (
          <Carousel.Slide key={index}>
            <div
              className='demo-carousel-gradient'
              style={{
                background: `linear-gradient(to right, ${from}, ${to})`,
              }}
            >
              <div className='demo-carousel-number'>{index + 1}</div>
            </div>
          </Carousel.Slide>
        ))}
      </Carousel.Slider>
    </Carousel>
  );
};

Accessibility

The Carousel component is built with accessibility in mind and tested to work well with different input modalities. It includes support for keyboard users and touch-screen users.

The component is loosely based on the APG Tabs pattern, where the dots are considered to be “tabs” and the slides are considered to be “panels”. For this reason, it is important that the dots (navigation section) is present before the slides in DOM order.

When a slide is changed, all inactive slides will become “inert” so that they cannot be interacted with by users of assistive technology.

Lastly, the carousel does not support auto-rotating slides, because that can lead to many different accessibility and usability issues. We do not recommend implementing your own auto-rotating carousel unless you have done extensive research and testing with users (including users with disabilities).

Component API

Carousel exposes the following subcomponents. The usage of all subcomponents is not mandatory; some of them (e.g. Carousel.Navigation) will automatically include recommended children and props by default.

Carousel

Carousel is the main component that orchestrates all other sub-components and maintains the overall state.

Carousel.Slider

Carousel.Slider is the scrollable list that should consist of Carousel.Slide components.

Carousel.Slide

Carousel.Slide is used for the actual slide content. The content can be specified through children. It is recommended that the slide content bring its own dimensions (esp. height) and that the dimensions should be the same for all slides.

Carousel.Navigation

The Carousel.Navigation component by default consists of the PreviousButton and NextButton shown on the left and right and the Carousel.DotsList component shown in the middle. children can be specified to override what is shown in this navigation section.

Important: The navigation section must always be present before the slides in DOM order.

Carousel.Navigation.PreviousButton

The Carousel.Navigation.PreviousButton component facilitates navigation to the previous slide in the carousel.

Carousel.Navigation.NextButton

The Carousel.Navigation.NextButton component enables navigation to the next slide in the carousel.

Carousel.DotsList

The Carousel.DotsList component shows a list of Carousel.Dot components which can be used to choose a specific slide.

If used as a descendant of Carousel, then this component does not need any props or children. children can be specified to override the individual dots that are shown. The props can be specified if this component is being used standalone (outside Carousel).

When used standalone, it is important to pay close attention to accessibility, since you may be missing some parts that make the carousel pattern complete. For this reason, we do not recommend diverging from the standard usage unless you have a very strong need and are confident that you can implement it accessibly.

Carousel.Dot

Carousel.Dot is the actual “dot” component used to activate a slide on clicking. It should be used as a child of Carousel.DotsList.