--- title: "Carousel — React" canonical: https://sky-ui.cf.sky.com/components/carousel/react apiPackages: [{"name":"@sky-uk/ui-core","representedVersion":"13.2.0"}] --- # Carousel — React An infinite scrolling carousel showcasing visual content. ```js import { Carousel } from '@sky-uk/ui-core'; ``` --- The `Carousel` component provides you with an infinite scrolling carousel. ```tsx

``` --- ## Subcomponents - `Carousel.Controls` - applies the internal pagination controls that appear on top of the slides. - `Carousel.Slide` - individual slides allowing the content of each slide to be dictated. Supports the `description` property. - `Carousel.Scrim` – applies the gradient scrim to the left and right of the `Carousel`. Supports the `$backgroundColor` property to apply a [theme color](/foundations/colours/) to the gradient. Additionally supports the `$opaque` property to force the `$backgroundColor` gradient to end on a solid theme color --- ## Variants ### Basic Carousel The below example shows the basic `Carousel`, with every optional element turned off. ```tsx

``` ### Media Carousel The below example shows the full media `Carousel` with the `$peek` property on. ```tsx

``` --- ## Props ### $peek `$peek` is a boolean property which when set shows the next and previous slide including a scrim overlay. ```tsx

``` ### $scrollableRegionTabIndex `$scrollableRegionTabIndex` is a boolean property which when set on the `Carousel` component will allow the user to tab into the `Carousel`. Note: this prop should only be used if the rail has non-interactive content. ```tsx

``` ### $mediaControls `$mediaControls` is a boolean property which when set on the `Carousel` component renders media controls on all child slides. `$mediaControls` can also be set on individual slides if the controls are only required on particular slides. `$mediaControls` set on the `Carousel` will take precedence. #### autoplay / muted The `Carousel` accepts two additional properties related to the `$mediaControls`. - `autoplay` is a boolean property that sets the state of the `autoplay` button, this is `false` by default. - `muted` is a boolean property that sets the state of the `muted` button, this is `true` by default. ```tsx

``` --- ## Callbacks ### onMount The `onMount` callback will return an `array` containing `ref`s to all the slides, including the duplicates, in the `Carousel` track. This can be used to manage the state of the slides. ```tsx () => { function Example(){ const [allSlides, setAllSlides] = React.useState([]); const handleMount = e => { setAllSlides(e); } return ( All slides:

{(slide.ref && slide.ref.current) && slide.ref.current.className}

); } return } ``` ### onSlideChange The `onSlideChange` callback will return the state of slide slides as an `object` when the transition to the new current slide is complete. The `current` key is the 0 indexed current slide as a `number`. The `ref` key is a `ref` to the current slide. ```tsx () => { function Example(){ const [slideState, setSlideState] = React.useState({ current: null }); const handleSlideChange = e => { setSlideState(e); }; return ( Current slide: {slideState.current}

); } return } ``` ### onMediaControlChange The `onMediaControlChange` callback will return the state of the media controls as an `object` when any of the media controls change. Management of the media's properties is the concern of the consumer. ```tsx () => { function Example(){ const [mediaControls, setMediaControls] = React.useState({ autoplay: false, muted: true }); const [allSlides, setAllSlides] = React.useState([]); const [currentSlide, setCurrentSlide] = React.useState({ current: 0, ref: undefined }); const handleMount = e => { setAllSlides(e); } const getSlideVideo = slide => { const slideRefCurrent = slide.ref.current; if (!slideRefCurrent) return null; const video = slideRefCurrent.firstChild return video.nodeName === 'VIDEO' ? video : null; } const handleAllSlides = () => { const slides = allSlides.filter((slide) => slide.ref.current !== currentSlide.ref.current); if (!slides.length) return; slides.map(slide => { if (!slide.ref) return; const video = getSlideVideo(slide); video.currentTime = 0; video.pause(); return; }); } const handleCurrentSlide = () => { if (!currentSlide.ref) return; const video = getSlideVideo(currentSlide); if(!video) return; if (mediaControls.autoplay) { video.currentTime = 0; video.play(); return; } video.pause(); } const handleMediaControlChange = e => { setMediaControls(e); }; const handleSlideChange = e => { setCurrentSlide(e); }; React.useEffect(() => { handleCurrentSlide() }, [mediaControls, currentSlide]); return ( Media controls autoplay: {String(mediaControls.autoplay)} muted: {String(mediaControls.muted)}

); } return } ``` ## Functions The `Carousel` supports functions to programmatically scroll or snap to slides. Use the `ref` prop to get a reference to the `Carousel` component and call the function on the reference. | Function | Props | Description | | --- | --- | --- | | `moveNext` | | Scrolls the Carousel to the next slide | | `movePrevious` | | Scrolls the Carousel to the previous slide | | `moveTo` | `number` | Scrolls the Carousel to the slide at the provided value | | `snapTo` | `number` | Snaps the Carousel to the slide at the provided value | ```tsx function Example() { const carouselRef = React.useRef(null); const [snapToValue, setSnapToValue] = React.useState(0); const [moveToValue, setMoveToValue] = React.useState(0); const handleNext = () => { if (carouselRef.current) { carouselRef.current.moveNext(); } }; const handlePrevious = () => { if (carouselRef.current) { carouselRef.current.movePrevious(); } }; const handleSnapTo = () => { carouselRef.current.snapTo(snapToValue); }; const handleMoveTo = () => { carouselRef.current.moveTo(moveToValue); }; return ( setSnapToValue(Number(e.target.value)) }} buttonProps={{ text: 'snapTo', onClick: handleSnapTo }} /> setMoveToValue(Number(e.target.value)) }} buttonProps={{ text: 'moveTo', onClick: handleMoveTo }} />

); } ``` --- ## Light variant Use `$appearance` to alternate between `default` and `light` to provide contrast on shaded backgrounds. ```tsx

``` --- ## Accessibility The `Carousel` will automatically handle accessibility inline with the w3c recommendation. You will need to pass your own unique `aria-label` to the component to fully comply. [(See W3C)](https://www.w3.org/WAI/tutorials/carousels/). ```jsx

``` --- ## System Modifiers The `Carousel` component also accepts props applied using the following system modifiers: - [margin](/core/system/margin/) --- ## Translatable Fields The `Carousel` support translation on the following fields: - `carousel.roleDescription` - controls the roleDescription. [(See MDN)](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) - `carousel.paginationDivider.label` - controls the descriptive text for the pagination divider - `carousel.previous.label` - controls the descriptive text for the previous slide action - `carousel.next.label` - controls the descriptive text for the next slide action For more on translatable fields, view the `useTranslation` docs here: [useTranslation](/core/hooks/use-translation/)