React Carousel Overview

The Ignite UI for React Carousel is a responsive, lightweight component that provides the most flexible way to create slideshow-like web experience for users who navigate back and forth through a collection of images with text slides, links, and other html elements.

The React Carousel component allows you to use animations, slide transitions, and customization so you can easily tweak the interface and build React custom carousel.

React Carousel Example

The React Carousel demo you see below shows slides containing only images.

Usage

First, you need to the install the corresponding Ignite UI for React npm package by running the following command:

npm install igniteui-react

You will then need to import the IgrCarousel, its necessary CSS, and register its module, like so:

import { IgrCarouselModule, IgrCarousel, IgrCarouselSlide } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

IgrCarouselModule.register();

For a complete introduction to the Ignite UI for React, read the Getting Started topic.

Now that you have the Ignite UI for React Carousel imported, you can start with a basic configuration of the IgrCarousel and its slides.

Use the IgrCarousel selector to wrap your slides. The slides may feature any valid html content inside, including other components.

<IgrCarousel>
    <IgrCarouselSlide key="first">
        <img src="assets/images/carousel/ignite-ui-angular-indigo-design.png" key="img"/>
    </IgrCarouselSlide>
    <IgrCarouselSlide key="second">
        <img src="assets/images/carousel/slider-image-chart.png" key="img"/>
    </IgrCarouselSlide>
    <IgrCarouselSlide key="third">
        <img src="assets/images/carousel/ignite-ui-angular-charts.png" key="img"/>
    </IgrCarouselSlide>
</IgrCarousel>

If you want a slide to be active by default, use the Active attribute:

<IgrCarousel>
    ...
    <IgrCarouselSlide key="first">
        ...
    </IgrCarouselSlide>
    <IgrCarouselSlide active={true} key="second">
        ...
    </IgrCarouselSlide>
</IgrCarousel>

[!NOTE] If no active slide is set, the first one will be set by default. If there are multiple active slides on initial rendering or subsequent updates, only the last one will be taken into account.

Examples

Carousel Configuration

By default, the IgrCarousel has its disableLoop property set to false (looping occurs when the first slide comes after the last by navigating using the Next action, or when the last slide comes after the first by using the Previous action). The looping behavior can be disabled by setting the value of the disableLoop property to true.

<IgrCarousel disableLoop={true}>
    ...
</IgrCarousel>

To keep track of each slide index, the carousel has indicators that are positioned at the end of the carousel by default. In order to change this behavior, use the indicatorsOrientation property and assign it to start.

<IgrCarousel indicatorsOrientation={CarouselIndicatorsOrientation.Start}>
    ...
</IgrCarousel>

By default, the IgrCarousel displays its navigation buttons and indicators. Use the hideIndicators property to hide the indicators and the hideNavigation property to hide the navigation buttons.

<IgrCarousel hideNavigation={true} hideIndicators={true}>
    ...
</IgrCarousel>

The IgrCarousel supports vertical mode. Use the vertical property to enable it.

<IgrCarousel vertical={true}>
    ...
</IgrCarousel>

Custom indicators

To add React custom carousel indicators, use the IgrCarouselIndicator:

<IgrCarousel>
    <IgrCarouselIndicator key="first-indicator">
        <span key="empty">🤍</span>
        <span slot="active" key="active">❤️</span>
    </IgrCarouselIndicator>
    <IgrCarouselIndicator key="second-indicator">
        <span key="empty">🤍</span>
        <span slot="active" key="active">❤️</span>
    </IgrCarouselIndicator>

    <IgrCarouselSlide key="first">
        <img src="assets/images/card/media/the_red_ice_forest.jpg" key="img"/>
    </IgrCarouselSlide>
    <IgrCarouselSlide key="second">
        <img src="assets/images/card/media/yosemite.jpg" key="img"/>
    </IgrCarouselSlide>
</IgrCarousel>

The Ignite UI for React Carousel component allows users to use different elements for the active and inactive state of a single indicator. It is mandatory to provide two elements for each slot (empty and active) when declaring an indicator, even if they are the same.

Custom navigation buttons

To achieve this, use the previous-button and next-button slots:

<IgrCarousel>
    <IgrIcon slot="previous-button" name="previous" collection="material" key="previous"></IgrIcon>
    <IgrIcon slot="next-button" name="next" collection="material" key="next"></IgrIcon>
    ...
</IgrCarousel>

Slide containing other components

This carousel is going to contain slides with forms and images:

<IgrCarousel>
    <IgrCarouselSlide key="slide-1">
        <div key="slide-content">
            <img src="assets/images/svg/carousel/SignUp.svg"/>
            <form>
                <IgrInput type="text" placeholder="Username">
                    <IgrIcon slot="prefix" name="person" key="icon"></IgrIcon>
                </IgrInput>
                <IgrInput type="password" placeholder="Password">
                    <IgrIcon slot="prefix" name="password" key="icon"></IgrIcon>
                </IgrInput>
                <IgrButton type="reset">
                    <span key="button-span">Sign In</span>
                </IgrButton>
            </form>
        </div>
    </IgrCarouselSlide>
    <IgrCarouselSlide key="slide-2">
        <div key="slide-content">
            <img src="assets/images/svg/carousel/Route.svg"/>
            <form>
                <IgrInput type="text" placeholder="Search">
                    <IgrIcon slot="prefix" name="search" key="icon"></IgrIcon>
                </IgrInput>
                <IgrButton type="reset">
                    <span key="button-span">Search</span>
                </IgrButton>
            </form>
        </div>
    </IgrCarouselSlide>
</IgrCarousel>

Demo

Animations

Animated slide transitions provide the end-users a nice experience when interacting with the carousel.

The carousel is configured to use the slide animation by default, but it also supports fade as an alternative animation.

Use the animationType property to change the animation.

<IgrCarousel animationType={CarouselAnimationType.Fade}>
    ...
</IgrCarousel>

Setting none to the animationType property disables the animations.

Demo

The demo below demonstrates the different types of animations, which the carousel supports.

Navigation

Transition and navigation are the most important carousel features.

The navigation in the carousel can be handled by the user through navigation buttons, indicators, keyboard navigation and touch interaction on mobile devices.

Touch gestures

By default, the carousel can be used on any touch-enabled device.

The carousel animations are fully supported on touch devices, which makes the carousel consistent with any platform and great when used in progressive web applications (PWA).

Keyboard navigation

• Navigation buttons
  • Space/Enter key - navigates to the next/previous slide.
• Indicators
  • Arrow Left key - navigates to the previous (next in Right-to-Left mode) slide.
  • Arrow Right key - navigates to the next (previous in Right-to-Left mode) slide.
  • Home key - navigates to the first (last in Right-to-Left mode) slide.
  • End key - navigates to the last (first in Right-to-Left mode) slide.

Automatic transitioning

The IgrCarousel can be easily configured to change the slides automatically, without any user interaction. This way you can create your own slideshow by only setting a transition interval to the interval property, which determines the amount of time in milliseconds between slides transition.

[!NOTE] Hovering the mouse over any carousel content or moving keyboard focus to any of the carousel content pauses automatic transitioning. Automatic transitioning resumes when the mouse moves away from the carousel or when keyboard focus moves out of the carousel content. This can be prevented by setting disablePauseOnInteraction property to true.

<IgrCarousel interval={2000} disablePauseOnInteraction={true}>
    ...
</IgrCarousel>

Advanced Example

Let's create a fully automated carousel with looping enabled. We will configure the indicators to be a thumbnail representation of each slide.

To achieve this goal, we have to do the following configurations to the carousel:

• enable the disablePauseOnInteraction property
• enable the hideNavigation property
• enable the vertical property
• add transition interval
• add custom IgrCarouselIndicator for each slide

Our carousel will look like this in the template:

const images = [
    {
        src: "assets/images/carousel/WonderfulCoast.png",
        alt: "Wonderful Coast",
    },
    {
        src: "assets/images/carousel/CulturalDip.png",
        alt: "Cultural Dip",
    },
    {
        src: "assets/images/carousel/GoldenBeaches.png",
        alt: "Golden Beaches",
    },
    {
        src: "assets/images/carousel/IslandOfHistory.png",
        alt: "Island Of History",
    },
    {
        src: "assets/images/carousel/AmazingBridge.png",
        alt: "Amazing Bridge",
    },
];

<IgrCarousel
    disablePauseOnInteraction={true}
    hideNavigation={true}
    interval={2000}
    vertical={true}
    animationType={CarouselAnimationType.Fade}
>
    {images.map((image, index) => {
        return (
            <React.Fragment key={index}>
                <IgrCarouselSlide key={`slide-${index}`}>
                    <img src={image.src} alt={image.alt} key="slide-img" />
                </IgrCarouselSlide>
                <IgrCarouselIndicator key={`indicator-${index}`}>
                    <img
                        key="img-blur"
                        className="blurred"
                        src={image.src.replace(".png", "Thumb.png")}
                        alt={`${image.alt} Thumb`}
                        width="50"
                        height="60"
                    />
                    <img
                        key="img-active"
                        slot="active"
                        src={image.src.replace(".png", "Thumb.png")}
                        alt={`${image.alt} Thumb Active`}
                        width="50"
                        height="60"
                    />
                </IgrCarouselIndicator>
            </React.Fragment>
        );
    })}
</IgrCarousel>

These configurations will have the following result:

Accessibility

WAI-ARIA Roles, States, and Properties

• The Carousel base element role is region - section containing content that is relevant to specific purpose and users will likely want to be able to navigate easily.
• Carousel indicators are with role tab - grouping label providing a mechanism for selecting the tab content that is to be rendered to the user
• The element that serves as the container for the set of tabs (carousel indicators) is with role tablist.
• Each slide element is set with role tabpanel.

ARIA support

Carousel component

• Attributes
  • aria-roledescription set to "carousel".
  • aria-live - used to set the priority with which screen reader should treat updates to live regions - the possible settings are: off and polite. The default setting is polite and is set to the element that serves as the container for the set of slides. When the interval option is set and the carousel is in playing state, the aria-live attribute would be set to off.
  • aria-label (navigation buttons) - "Previous slide"/"Next slide".

Slide component

• Attributes
  • id - follows the pattern "igc-carousel-slide-${incremented_number}".
  • aria-roledescription set to "slide".
  • aria-label follows the pattern "${index + 1} of ${total}".

Indicator component

• Attributes
  • aria-label follows the pattern "Slide ${index + 1}"
  • aria-selected set to true or false based on the active slide.

API References

• IgrCarousel
• IgrCarouselSlide
• IgrCarouselIndicator
• IgrIcon
• IgrInput
• IgrButton

Additional Resources

• Ignite UI for React Forums
• Ignite UI for React GitHub