diff --git a/.cspell.json b/.cspell.json index d528823b1d..752acd5218 100644 --- a/.cspell.json +++ b/.cspell.json @@ -8,6 +8,7 @@ "autohiding", "autoplay", "autoplays", + "autoplaying", "blazingly", "Blockquotes", "Bootstrappers", diff --git a/site/assets/js/snippets.js b/site/assets/js/snippets.js index 53f8a786ec..43b8a095cf 100644 --- a/site/assets/js/snippets.js +++ b/site/assets/js/snippets.js @@ -96,6 +96,15 @@ }) } + // -------- + // Carousels + // -------- + // Instantiate all non-autoplaying carousels in a docs or StackBlitz page + document.querySelectorAll('.carousel:not([data-bs-ride="carousel"])') + .forEach(carousel => { + bootstrap.Carousel.getOrCreateInstance(carousel) + }) + // ------------------------------- // Checks & Radios // ------------------------------- diff --git a/site/content/docs/5.2/components/carousel.md b/site/content/docs/5.2/components/carousel.md index 95f4bf0301..dca8e9a792 100644 --- a/site/content/docs/5.2/components/carousel.md +++ b/site/content/docs/5.2/components/carousel.md @@ -8,28 +8,24 @@ toc: true ## How it works -The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators. +- The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators. -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.). +- For performance reasons, **carousels must be manually initialized** using the [carousel constructor method](#methods). Without initialization, some of the event listeners (specifically, the events needed touch/swipe support) will not be registered until a user has explicitly activated a control or indicator. + + The only exception are [autoplaying carousels](#autoplaying-carousels) with the `data-bs-ride="carousel"` attribute as these are initialized automatically on page load. If you're using autoplaying carousels with the data attribute, **don't explicitly initialize the same carousels with the constructor method.** + +- Nested carousels are not supported. You should also be aware that carousels in general can often cause usability and accessibility challenges. {{< callout info >}} {{< partial "callouts/info-prefersreducedmotion.md" >}} {{< /callout >}} -Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards. +## Basic examples -## Example - -Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they're not explicitly required. Add and customize as you see fit. - -**The `.active` class needs to be added to one of the slides** otherwise the carousel will not be visible. Also be sure to set a unique `id` on the `.carousel` for optional controls, especially if you're using multiple carousels on a single page. Control and indicator elements must have a `data-bs-target` attribute (or `href` for links) that matches the `id` of the `.carousel` element. - -### Slides only - -Here's a carousel with slides only. Note the presence of the `.d-block` and `.w-100` on carousel images to prevent browser default image alignment. +Here is a basic example of a carousel with three slides. Note the previous/next controls. We recommend using ` - {{< /example >}} -### With indicators +Carousels don't automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they're not explicitly required. Add and customize as you see fit. -You can also add the indicators to the carousel, alongside the controls, too. +**You must add the `.active` class to one of the slides**, otherwise the carousel will not be visible. Also be sure to set a unique `id` on the `.carousel` for optional controls, especially if you're using multiple carousels on a single page. Control and indicator elements must have a `data-bs-target` attribute (or `href` for links) that matches the `id` of the `.carousel` element. + +### Indicators + +You can add indicators to the carousel, alongside the previous/next controls. The indicators let users jump directly to a particular slide. {{< example >}} -