bootstrap_ref_js_carousel

Bootstrap JS Carousel

JS Carousel (carousel.js)

The Carousel plugin is a component for cycling through elements, like a slideshow. It’s built with CSS 3D transforms and JavaScript and requires the Bootstrap JavaScript library (bootstrap.bundle.min.js which includes Popper, or individual files).

For a step-by-step tutorial about Carousels, read our Bootstrap Carousel Tutorial.

Note: Carousels are generally well-supported in modern browsers that support CSS3 transitions and animations. Nested carousels are not supported.

The Carousel Plugin Classes

Class	Description
.carousel	The main container for the carousel.
.carousel-inner	Container for the slides (.carousel-item elements).
.carousel-item	Defines a single slide within the carousel. One item must have the .active class.
.carousel-item.active	Indicates the currently visible slide.
.carousel-control-prev	Adds a ‘previous’ button to navigate slides.
.carousel-control-next	Adds a ‘next’ button to navigate slides.
.carousel-control-prev-icon	Icon for the ‘previous’ button (typically an SVG).
.carousel-control-next-icon	Icon for the ‘next’ button (typically an SVG).
.carousel-indicators	Container for the slide indicators (small dots). Individual indicators are <button> elements.
.carousel-caption	Container for optional captions within a .carousel-item.
.carousel-fade	Add to .carousel to animate slides with a fade transition instead of a slide.

Via data-* Attributes

Bootstrap carousels can be controlled entirely through data attributes:

• data-bs-ride="carousel": (On the main .carousel element) Activates the carousel on page load and makes it start cycling.
• data-bs-ride="true": (On the main .carousel element, added in Bootstrap 5.2) Similar to data-bs-ride="carousel", auto-starts the carousel if JavaScript is enabled.
• data-bs-target="#myCarousel": (On indicators and controls) Points to the ID of the carousel.
• data-bs-slide-to="0": (On an indicator) Navigates to the slide with the specified index (0-based).
• data-bs-slide="prev": (On a control) Navigates to the previous slide.
• data-bs-slide="next": (On a control) Navigates to the next slide.

Example of data attributes in action:

<!-- Carousel -->
<div id="myCarousel" class="carousel slide" data-bs-ride="carousel">
  <!-- Carousel Indicators -->
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="1" aria-label="Slide 2"></button>
  </div>
  <!-- Carousel Controls -->
  <button class="carousel-control-prev" type="button" data-bs-target="#myCarousel" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#myCarousel" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
  <!-- Carousel Inner (slides) would go here -->
</div>

Via JavaScript

You can also initialize and control carousels manually using JavaScript:

// Get the carousel element
var myCarouselElement = document.querySelector('#myCarousel');

// Initialize the carousel
var carousel = new bootstrap.Carousel(myCarouselElement, {
  interval: 2000, // Optional: set interval
  wrap: false     // Optional: prevent continuous cycling
});

// Example: Go to a specific slide (e.g., slide 1, which is index 1)
// carousel.to(1);

// Example: Go to previous slide
// carousel.prev();

// Example: Cycle items
// carousel.cycle();

// Example: Pause cycling
// carousel.pause();

Carousel Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-bs-, as in data-bs-interval="".

Name	Type	Default	Description
interval	number | boolean	5000	The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.
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.
ride	string | boolean	false	If set to "carousel" or true, autoplays the carousel after the user manually cycles the first item. If set to false, it will not autoplay.
wrap	boolean	true	Whether the carousel should cycle continuously or stop at the last slide.
touch	boolean	true	Whether the carousel should support left/right swipe interactions on touchscreen devices.

Carousel Methods

The following table lists available carousel methods, which can be called on the carousel instance (e.g., myCarouselInstance.next()).

Method	Description
.carousel(options) or new bootstrap.Carousel(element, options)	Initializes the carousel with optional options.
.cycle()	Cycles through the carousel items from left to right.
.pause()	Stops the carousel from cycling through items.
.prev()	Cycles to the previous item.
.next()	Cycles to the next item.
.nextWhenVisible()	Cycles to the next item only if the page is visible (useful for performance).
.to(number)	Cycles the carousel to a particular frame (0-based, similar to an array).
.dispose()	Destroys an element’s carousel. (Removes event listeners and data attributes).

Carousel Events

Bootstrap’s carousel exposes two events for hooking into carousel functionality. All carousel events are fired at the carousel itself (i.e. at the <div class="carousel">).

Event Type	Description
slide.bs.carousel	This event fires immediately when the slide instance method is invoked.
slid.bs.carousel	This event is fired when the carousel has completed its slide transition.

Example of using an event:

var myCarousel = document.getElementById('myCarousel');
myCarousel.addEventListener('slide.bs.carousel', function (event) {
  // event.direction: The direction in which the carousel is sliding (either "left" or "right").
  // event.relatedTarget: The DOM element that is being slid into place as the active item.
  // event.from: The index of the current item.
  // event.to: The index of the next item.
  console.log('Carousel is about to slide from ' + event.from + ' to ' + event.to);
});

Captions to Slides

Add <div class="carousel-caption"> within each <div class="carousel-item"> to create a caption for each slide. Captions can be hidden on smaller viewports using display utilities like .d-none .d-md-block.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Bootstrap Carousel with Captions</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
  <style>
    .carousel-item img {
      max-height: 400px; /* Example height, adjust as needed */
      object-fit: cover;
      width: 100%;
    }
  </style>
</head>
<body>

<div id="myCarousel" class="carousel slide" data-bs-ride="carousel">
  <!-- Indicators -->
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#myCarousel" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>

  <!-- Wrapper for slides -->
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="docs/english/books/bootstrap/images/cinqueterre.jpg" class="d-block w-100" alt="Chania">
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label (Chania)</h5>
        <p>The atmosphere in Chania has a touch of Florence and Venice.</p>
      </div>
    </div>

    <div class="carousel-item">
      <img src="docs/english/books/bootstrap/images/img_chania2.jpg" class="d-block w-100" alt="Another view of Chania">
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label (Chania)</h5>
        <p>Exploring the beautiful streets and architecture.</p>
      </div>
    </div>

    <div class="carousel-item">
      <img src="docs/english/books/bootstrap/images/img_flower.jpg" class="d-block w-100" alt="Flower">
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label (Flowers)</h5>
        <p>Beautiful flowers in Kolymbari, Crete.</p>
      </div>
    </div>
  </div>

  <!-- Left and right controls -->
  <button class="carousel-control-prev" type="button" data-bs-target="#myCarousel" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#myCarousel" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>