Carousel

A slideshow component for cycling through elements—images or slides of text—like a carousel.

How it works #

With the help of CSS 3D transformations and a little JavaScript, the carousel is a slideshow that cycles through a variety of content. It functions with a collection of pictures, text, or unique markup. Support for previous/next buttons and indicators is also included.

When a user cannot see a webpage (for example, when a browser tab is idle or a browser window is minimized), the carousel won't slide in browsers that use the Page Visibility API.

This component's animation effect depends on the prefers-reduced-motion media query. See the accessibility documentation section on the reduced motion.

Please be advised that carousels do not normally adhere to accessibility requirements and that nested carousels are not supported.

Example #

Slide dimensions are not automatically normalized for carousels. As a result, there might be a need to employ extra tools or unique styles to size content properly. Although previous/next controls and indicators are supported by carousels, they are not strictly necessary. As it is seen fit, add and modify.

The carousel cannot be seen unless the .active class is added to one of the slides. If there is a utilization of numerous carousels on a single page, specifically, make sure to set a distinct id on the .carousel for optional controls. A data-bs-target attribute (or href for links) on control and indicator elements must match the id of the .carousel element.

Slides only #

Here is a carousel that simply has slides. The .d-block and are present on carousel pictures to prevent browser default image alignment.

<div id="carouselExampleSlidesOnly" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
  </div>
</div>

RESULT

With controls #

The previous and next controls should be included. Although <button> elements are advised, <a> elements can also be used if the role attribute is set to "button".

<div id="carouselExampleControls" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControls" 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="#carouselExampleControls" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

RESULT

With indicators #

You can also add the indicators to the carousel, alongside the controls, too.

<div id="carouselExampleIndicators" class="carousel slide" data-bs-ride="true">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleIndicators" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleIndicators" 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="#carouselExampleIndicators" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

RESULT

With captions #

The .carousel-caption element found within any .carousel-item makes it simple to add captions to your slides. With optional display utilities, they can be quickly hidden on smaller viewports, as demonstrated below. Initially conceal them with .d-none and reveal them on medium-sized devices using .d-md-block.

<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="false">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="/assets/placeholder.jpg" class="d-block " />
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" 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="#carouselExampleCaptions" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

RESULT


First slide label
Some representative placeholder content for the first slide.
Second slide label
Some representative placeholder content for the second slide.
Third slide label
Some representative placeholder content for the third slide.

Crossfade #

To animate slides with a fade transition rather than a slide, add the class .carousel-fade to your carousel. For appropriate crossfading, there might be a need to add .bg-body or other custom CSS to the .carousel-items depending on your carousel content (for example, text-only slides).

<div id="carouselExampleFade" class="carousel slide carousel-fade" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleFade" 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="#carouselExampleFade" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

RESULT

Individual `.carousel-item` interval #

To alter the interval between automatically cycling to the next item, add data-bs-interval="" to a .carousel-item.

<div id="carouselExampleInterval" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleInterval" 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="#carouselExampleInterval" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

RESULT

Disable touch swiping #

On touchscreen devices, carousels allows to swipe left or right to switch between slides. By utilizing the data-bs-touch attribute, this can be turned off. Additionally, the example below lacks the data-bs-ride feature and does not autoplay.

<div id="carouselExampleControlsNoTouching" class="carousel slide" data-bs-touch="false">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleControlsNoTouching" 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="#carouselExampleControlsNoTouching" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

RESULT

Dark variant #

To make controls, indicators, and captions darker, add the suffix .carousel-dark to the .carousel. With the filter CSS property, controls have been inverted from their white fill default. Additional Sass variables can be used to change the color and background-color of captions and controls.

<div id="carouselExampleDark" class="carousel carousel-dark slide" data-bs-ride="carousel">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="/assets/placeholder.jpg" class="d-block " />
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="/assets/placeholder.jpg" class="d-block " />
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="/assets/placeholder.jpg" class="d-block " />
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleDark" 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="#carouselExampleDark" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

RESULT

First slide label

Some representative placeholder content for the first slide.

Second slide label

Some representative placeholder content for the second slide.

Third slide label

Some representative placeholder content for the third slide.

Custom transition #

It is possible to modify the $carousel-transition-duration Sass variable before compilation or apply custom styles if there is a use of compiled CSS to alter the .carousel-item transition duration. Make sure the transform transition is defined first when using several transitions (for example, transition: transform 2s easy, opacity.5s ease-out).

Sass #

Variables #

Variables for all carousels:

$carousel-control-color:             $white;
$carousel-control-width:             15%;
$carousel-control-opacity:           .5;
$carousel-control-hover-opacity:     .9;
$carousel-control-transition:        opacity .15s ease;

$carousel-indicator-width:           30px;
$carousel-indicator-height:          3px;
$carousel-indicator-hit-area-height: 10px;
$carousel-indicator-spacer:          3px;
$carousel-indicator-opacity:         .5;
$carousel-indicator-active-bg:       $white;
$carousel-indicator-active-opacity:  1;
$carousel-indicator-transition:      opacity .6s ease;

$carousel-caption-width:             70%;
$carousel-caption-color:             $white;
$carousel-caption-padding-y:         1.25rem;
$carousel-caption-spacer:            1.25rem;

$carousel-control-icon-width:        2rem;

$carousel-control-prev-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z'/></svg>");
$carousel-control-next-icon-bg:      url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='#{$carousel-control-color}'><path d='M4.646 1.646a.5.5 0 0 1 .708 0l6 6a.5.5 0 0 1 0 .708l-6 6a.5.5 0 0 1-.708-.708L10.293 8 4.646 2.354a.5.5 0 0 1 0-.708z'/></svg>");

$carousel-transition-duration:       .6s;
$carousel-transition:                transform $carousel-transition-duration ease-in-out; // Define transform transition first if using multiple transitions (e.g., `transform 2s ease, opacity .5s ease-out`)

Usage #

Via data attributes #

To quickly control the position of the carousel, use data attributes. The keywords prev or next are accepted by data-bs-slide, which changes the slide position in relation to its current position. A different option is to pass a raw slide index to the carousel using data-bs-slide-to. For example, data-bs-slide-to="2" moves the slide position to a specific index starting with 0.

To indicate that a carousel will begin animating as the page loads, use the data-bs-ride="carousel" element. It is must to initialize the carousel manually if data-bs-ride="carousel" was not used to initialize it. It cannot be used in conjunction with the same carousel's (redundant and pointless) explicit JavaScript initialization.

Via JavaScript #

Call carousel manually with:

const carousel = new UX4G.Carousel('#myCarousel')

Options #

Data-bs-animation can have an option name appended to it, for example, data-bs-animation="value," since options can be provided through data attributes or JavaScript. When sending the choices via data attributes, be sure to modify the case type of the option name from "camelCase" to "kebab-case." Use data-bs-custom-class="beautifier" as opposed to data-bs-customClass="beautifier," for instance.

Since UX4G V1.0.0, all components are compatible with the experimental reserved data attribute data-bs-config, which can store a JSON string for basic component setting. When an element has the data-bs-config={"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the individual data attributes will take precedence over the values specified on the data-bs-config. Additionally, JSON variables like data-bs-delay='{"show":0,"hide":150}' can be stored in existing data attributes.

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

Every API method begins a transition and is asynchronous. When the transition begins, they call the caller back before it ends. A method call on a component that is transitioning will also be disregarded.

By using the carousel constructor, for instance, there is a possibility to create a carousel instance that is initialized with extra settings and begins iterating through the items:

const myCarouselElement = document.querySelector('#myCarousel')
const carousel = new UX4G.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: `UX4G.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: `UX4G.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.bs.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.bs.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.bs.carousel` event occurs).

Events #

The carousel class in UX4G exposes two events for carousel functionality hooking. The following additional characteristics apply to both events:

direction The direction (either "left" or "right") in which the carousel is moving.
relatedTarget: The DOM element that will become the active item when it is pushed into position.
from: The index of the current item is followed by the index of the following item.
to: The index of the next item

All carousel events are fired at the carousel itself (i.e. at the <div class="carousel">).

Event type	Description
`slid.bs.carousel`	Fired when the carousel has completed its slide transition.
`slide.bs.carousel`	Fires immediately when the `slide` instance method is invoked.

How it works
Example
Dark variant
Custom transition
Sass
- Variables
Usage
Methods
Events

Demo

Demo

Previous « Card

Next Close Button »

Carousel

How it works #

Example #

Slides only #

RESULT

With controls #

RESULT

With indicators #

RESULT

With captions #

RESULT

First slide label

Second slide label

Third slide label

Crossfade #

RESULT

Individual .carousel-item interval #

RESULT

Disable touch swiping #

RESULT

Dark variant #

RESULT

First slide label

Second slide label

Third slide label

Custom transition #

Sass #

Variables #

Usage #

Via data attributes #

Via JavaScript #

Options #

Methods #

Asynchronous methods and transitions

Events #

Individual `.carousel-item` interval #