# Bootstrap 5 Carousel > Bootstrap carousel is a slideshow component for cycling through elements—images or slides of text—like a carousel. ## How it works The bootstrap carousel is a slideshow for cycling within a group of content, built with CSS 3D transforms and JavaScript. It runs with a group of images, text, or html elements. It also incorporates support for previous/next buttons. In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibility/) is supported, the carousel will avoid sliding when the webpage is not visible to the user (such as when the browser tab is inactive, the browser window is minimized, etc.). > This component's animation effect relies on the `prefers-reduced-motion` media query. For more information, refer to the [reduced motion section of our accessibility documentation](https://coreui.io/bootstrap/docs/getting-started/accessibility/#reduced-motion). Please be informed that nested carousels are not supported, and carousels are frequently not compliant with accessibility rules. ## Example Carousels don't automatically normalize slide dimensions. As such, you may want to use extra utilities or custom methods to properly size content. While carousels support previous/next controls and indicators, they're not explicitly expected. Add and customize as you see fit. **The `.active` class must to be attached to one of the slides** otherwise the carousel will not be visible. Additionally be sure to set a different id on the `.carousel` for optional controls, particularly if you're using many carousels on a page. Control and indicator elements must have a `data-coreui-target` attribute (or `href` for links) that matches the id of the `.carousel` element. ### Slides only Here's a carousel with slides. Note the appearance of the `.d-block` also, `.w-100` on carousel images to override browser default image alignment. ```html ``` ### With controls Adding in the previous and next controls. We recommend using ` ``` ### With indicators You can attach the indicators to the carousel, lengthwise the controls, too. ```html ``` ### With captions You can add captions to slides with the `.carousel-caption` element within any `.carousel-item`. They can be immediately hidden on smaller viewports, as shown below, with optional [display utilities](https://coreui.io/bootstrap/docs/utilities/display/). We hide them with `.d-none` and draw them back on medium-sized devices with `.d-md-block`. ```html ``` ### Crossfade Add `.carousel-fade` to your carousel to animate slides with a fade transition instead of a slide. Depending on your carousel content (e.g., text only slides), you may want to add `.bg-body` or some custom CSS to the `.carousel-item`s for proper crossfading. ```html ``` ### Individual `.carousel-item` interval Add `data-coreui-interval=""` to a `.carousel-item` to change the amount of time to delay between automatically cycling to the next item. ```html ``` ### Disable touch swiping Carousels support swiping left/right on touchscreen devices to move between slides. This can be disabled using the `data-coreui-touch` attribute. The example below also does not include the `data-coreui-ride` attribute so it doesn't autoplay. ```html ``` ## Dark variant Add `.carousel-dark` to the `.carousel` for darker controls, indicators, and captions. Controls have been inverted from their default white fill with the `filter` CSS property. Captions and controls have additional Sass variables that customize the `color` and `background-color`. ```html ``` ## Custom transition The transition duration of `.carousel-item` can be changed with the `$carousel-transition-duration` Sass variable before compiling or custom styles if you're using the compiled CSS. If multiple transitions are applied, make sure the transform transition is defined first (eg. `transition: transform 2s ease, opacity .5s ease-out`). ## Usage ### Via data attributes Utilize data attributes to control the position of the carousel. `data-coreui-slide` allows the keywords `prev` or `next`, which changes the slide position corresponding to its current position. Alternatively, use `data-coreui-slide-to` to pass a raw slide index to the carousel `data-coreui-slide-to="2"`, which moves the slide position to a particular index beginning with `0`. The `data-coreui-ride="carousel"` attribute is applied to mark a carousel as animating starting at page load. **It cannot be done in combination with (redundant and unnecessary) explicit JavaScript initialization of the same carousel.** ### Via JavaScript Call carousel manually with: ```js const carousel = new coreui.Carousel('#myCarousel') ``` ### Options Options can be passed using data attributes or JavaScript. To do this, append an option name to `data-coreui-`, such as `data-coreui-animation="{value}"`. Remember to convert the case of the option name from "_camelCase_" to "_kebab-case_" when using data attributes. For instance, you should write `data-coreui-custom-class="beautifier"` rather than `data-coreui-customClass="beautifier"`. Starting with CoreUI 4.2.6, all components support an **experimental** reserved data attribute named `data-coreui-config`, which can contain simple component configurations as a JSON string. If an element has attributes `data-coreui-config='{"delay":50, "title":689}'` and `data-coreui-title="Custom Title"`, then the final value for `title` will be `Custom Title`, as the standard data attributes will take precedence over values specified in `data-coreui-config`. Moreover, existing data attributes can also hold JSON values like `data-coreui-delay='{"show":50, "hide":250}'`. | Name | Type | Default | Description | | --- | --- | --- | --- | | `interval` | number | `5000` | The amount of time to delay between automatically cycling an item. | | `keyboard` | boolean | `true` | Whether the carousel should react to keyboard events. | | `pause` | string, boolean | `"hover"` | If set to `"hover"`, pauses the cycling of the carousel on `mouseenter` and resumes the cycling of the carousel on `mouseleave`. If set to `false`, hovering over the carousel won't pause it. On touch-enabled devices, when set to `"hover"`, cycling will pause on `touchend` (once the user finished interacting with the carousel) for two intervals, before automatically resuming. This is in addition to the mouse behavior. | | `ride` | string, boolean | `false` | If set to `true`, autoplays the carousel after the user manually cycles the first item. If set to `"carousel"`, autoplays the carousel on load. | | `touch` | boolean | `true` | Whether the carousel should support left/right swipe interactions on touchscreen devices. | | `wrap` | boolean | `true` | Whether the carousel should cycle continuously or have hard stops. | ### Methods > #### Asynchronous methods and transitions > > All our API methods are **asynchronous** and initiate a **transition**. They return to the caller as soon as the transition begins but **before it concludes**. Furthermore, a method call on a **transitioning component will be ignored**. > > [Refer to our JavaScript documentation for further details](https://coreui.io/bootstrap/docs/getting-started/javascript/#asynchronous-functions-and-transitions). You can create a carousel instance with the carousel constructor, for example, to initialize with additional options and start cycling through items: ```js const myCarouselElement = document.querySelector('#myCarousel') const carousel = new coreui.Carousel(myCarouselElement, { interval: 2000, wrap: false }) ``` | Method | Description | | --- | --- | | `cycle` | Cycles through the carousel items from left to right. | | `dispose` | Destroys an element's carousel. (Removes stored data on the DOM element) | | `getInstance` | Static method which allows you to get the carousel instance associated to a DOM element, you can use it like this: `coreui.Carousel.getInstance(element)` | | `getOrCreateInstance` | Static method which returns a carousel instance associated to a DOM element or create a new one in case it wasn't initialized. You can use it like this: `coreui.Carousel.getOrCreateInstance(element)` | | `next` | Cycles to the next item. **Returns to the caller before the next item has been shown** (e.g., before the `slid.coreui.carousel` event occurs). | | `nextWhenVisible` | Don't cycle carousel to next when the page isn't visible or the carousel or its parent isn't visible. **Returns to the caller before the target item has been shown** | | `pause` | Stops the carousel from cycling through items. | | `prev` | Cycles to the previous item. **Returns to the caller before the previous item has been shown** (e.g., before the `slid.coreui.carousel` event occurs). | | `to` | Cycles the carousel to a particular frame (0 based, similar to an array). **Returns to the caller before the target item has been shown** (e.g., before the `slid.coreui.carousel` event occurs). | ### Events CoreUI for Bootstrap's carousel class exposes two events for hooking into carousel functionality. Both events have the following additional properties: - `direction`: The direction in which the carousel is sliding (either `"left"` or `"right"`). - `relatedTarget`: The DOM element that is being slid into place as the active item. - `from`: The index of the current item - `to`: The index of the next item All carousel events are fired at the carousel itself (i.e. at the `
`). | Event type | Description | | --- | --- | | `slid.coreui.carousel` | Fired when the carousel has completed its slide transition. | | `slide.coreui.carousel` | Fires immediately when the `slide` instance method is invoked. | ```js const myCarousel = document.getElementById('myCarousel') myCarousel.addEventListener('slide.coreui.carousel', event => { // do something... }) ``` ## Customizing ### SASS variables Variables for all carousels: ```scss $carousel-control-color: $white !default; $carousel-control-width: 15% !default; $carousel-control-opacity: .5 !default; $carousel-control-hover-opacity: .9 !default; $carousel-control-transition: opacity .15s ease !default; $carousel-control-icon-filter: null !default; $carousel-indicator-width: 30px !default; $carousel-indicator-height: 3px !default; $carousel-indicator-hit-area-height: 10px !default; $carousel-indicator-spacer: 3px !default; $carousel-indicator-opacity: .5 !default; $carousel-indicator-active-bg: $white !default; $carousel-indicator-active-opacity: 1 !default; $carousel-indicator-transition: opacity .6s ease !default; $carousel-caption-width: 70% !default; $carousel-caption-color: $white !default; $carousel-caption-padding-y: 1.25rem !default; $carousel-caption-spacer: 1.25rem !default; $carousel-control-icon-width: 2rem !default; $carousel-control-prev-icon-bg: url("data:image/svg+xml,") !default; $carousel-control-next-icon-bg: url("data:image/svg+xml,") !default; $carousel-transition-duration: .6s !default; $carousel-transition: transform $carousel-transition-duration ease-in-out !default; // Define transform transition first if using multiple transitions (e.g., `transform 2s ease, opacity .5s ease-out`) ``` Variables for the [dark carousel](#dark-variant): ```scss $carousel-dark-indicator-active-bg: $black !default; // Deprecated in v5.3.2 $carousel-dark-caption-color: $black !default; // Deprecated in v5.3.2 $carousel-dark-control-icon-filter: invert(1) grayscale(100) !default; // Deprecated in v5.3.2 ```