diff --git a/docs/components/carousel.md b/docs/components/carousel.md index 3942309f0f5b..8dd819fba110 100644 --- a/docs/components/carousel.md +++ b/docs/components/carousel.md @@ -5,7 +5,11 @@ description: A slideshow component for cycling through elements—images or slid group: components --- -A slideshow component for cycling through elements—images or slides of text—like a carousel. 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.). **Nested carousels are not supported.** +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.). + +Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards. ## Contents @@ -14,32 +18,86 @@ A slideshow component for cycling through elements—images or slides of text— ## Example -When building carousels, be sure your slides are the same size as one another. The carousel doesn't automatically crop images to the same dimensions for you across slides. +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. + +Be sure to set a unique id on the `.carousel` for optional controls, especially if you're using multiple carousels on a single page. + +### Slides only + +Here's a carousel with slides only. Note the presence of the `.d-block` and `.img-fluid` on carousel images to prevent browser default image alignment. + +{% example html %} +
+{% endexample %} + +### With controls + +Adding in the previous and next controls: + +{% example html %} + +{% endexample %} + +### With indicators + +You can also add the indicators to the carousel, alongside the controls, too. {% example html %} -