diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/components/carousel.md | 124 | ||||
| -rw-r--r-- | docs/examples/carousel/carousel.css | 18 | ||||
| -rw-r--r-- | docs/examples/carousel/index.html | 20 | ||||
| -rw-r--r-- | docs/migration.md | 9 |
4 files changed, 109 insertions, 62 deletions
diff --git a/docs/components/carousel.md b/docs/components/carousel.md index 3942309f0..8dd819fba 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 %} +<div id="carouselExampleSlidesOnly" class="carousel slide" data-ride="carousel"> + <div class="carousel-inner" role="listbox"> + <div class="carousel-item active"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> + </div> + <div class="carousel-item"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> + </div> + <div class="carousel-item"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> + </div> + </div> +</div> +{% endexample %} + +### With controls + +Adding in the previous and next controls: + +{% example html %} +<div id="carouselExampleControls" class="carousel slide" data-ride="carousel"> + <div class="carousel-inner" role="listbox"> + <div class="carousel-item active"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> + </div> + <div class="carousel-item"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> + </div> + <div class="carousel-item"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> + </div> + </div> + <a class="carousel-control-prev" href="#carouselExampleControls" role="button" data-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> + <span class="sr-only">Previous</span> + </a> + <a class="carousel-control-next" href="#carouselExampleControls" role="button" data-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> + <span class="sr-only">Next</span> + </a> +</div> +{% endexample %} + +### With indicators + +You can also add the indicators to the carousel, alongside the controls, too. {% example html %} -<div id="carousel-example-generic" class="carousel slide" data-ride="carousel"> +<div id="carouselExampleIndicators" class="carousel slide" data-ride="carousel"> <ol class="carousel-indicators"> - <li data-target="#carousel-example-generic" data-slide-to="0" class="active"></li> - <li data-target="#carousel-example-generic" data-slide-to="1"></li> - <li data-target="#carousel-example-generic" data-slide-to="2"></li> + <li data-target="#carouselExampleIndicators" data-slide-to="0" class="active"></li> + <li data-target="#carouselExampleIndicators" data-slide-to="1"></li> + <li data-target="#carouselExampleIndicators" data-slide-to="2"></li> </ol> <div class="carousel-inner" role="listbox"> <div class="carousel-item active"> - <img data-src="holder.js/900x500/auto/#777:#555/text:First slide" alt="First slide"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> </div> <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#666:#444/text:Second slide" alt="Second slide"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> </div> <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#555:#333/text:Third slide" alt="Third slide"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> </div> </div> - <a class="left carousel-control" href="#carousel-example-generic" role="button" data-slide="prev"> - <span class="icon-prev" aria-hidden="true"></span> + <a class="carousel-control-prev" href="#carouselExampleIndicators" role="button" data-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> <span class="sr-only">Previous</span> </a> - <a class="right carousel-control" href="#carousel-example-generic" role="button" data-slide="next"> - <span class="icon-next" aria-hidden="true"></span> + <a class="carousel-control-next" href="#carouselExampleIndicators" role="button" data-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> <span class="sr-only">Next</span> </a> </div> @@ -57,45 +115,45 @@ Bootstrap exclusively uses CSS3 for its animations, but Internet Explorer 9 does The `.active` class needs to be added to one of the slides. Otherwise, the carousel will not be visible. {% endcallout %} -### Optional captions +### With captions -Add captions to your slides easily with the `.carousel-caption` element within any `.carousel-item`. Place just about any optional HTML within there and it will be automatically aligned and formatted. +Add captions to your slides easily with the `.carousel-caption` element within any `.carousel-item`. They can be easily hidden on smaller viewports, as shown below, with optional [display utilities]({{ site.baseurl }}/utilities/display-property/). We hide them initially with `.d-none` and bring them back on medium-sized devices with `.d-md-block`. <div class="bd-example"> - <div id="carousel-example-captions" class="carousel slide" data-ride="carousel"> + <div id="carouselExampleCaptions" class="carousel slide" data-ride="carousel"> <ol class="carousel-indicators"> - <li data-target="#carousel-example-captions" data-slide-to="0" class="active"></li> - <li data-target="#carousel-example-captions" data-slide-to="1"></li> - <li data-target="#carousel-example-captions" data-slide-to="2"></li> + <li data-target="#carouselExampleCaptions" data-slide-to="0" class="active"></li> + <li data-target="#carouselExampleCaptions" data-slide-to="1"></li> + <li data-target="#carouselExampleCaptions" data-slide-to="2"></li> </ol> <div class="carousel-inner" role="listbox"> <div class="carousel-item active"> - <img data-src="holder.js/900x500/auto/#777:#777" alt="First slide image"> - <div class="carousel-caption"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> + <div class="carousel-caption d-none d-md-block"> <h3>First slide label</h3> <p>Nulla vitae elit libero, a pharetra augue mollis interdum.</p> </div> </div> <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#666:#666" alt="Second slide image"> - <div class="carousel-caption"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> + <div class="carousel-caption d-none d-md-block"> <h3>Second slide label</h3> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> </div> </div> <div class="carousel-item"> - <img data-src="holder.js/900x500/auto/#555:#555" alt="Third slide image"> - <div class="carousel-caption"> + <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> + <div class="carousel-caption d-none d-md-block"> <h3>Third slide label</h3> <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur.</p> </div> </div> </div> - <a class="left carousel-control" href="#carousel-example-captions" role="button" data-slide="prev"> + <a class="carousel-control carousel-control-left" href="#carouselExampleCaptions" role="button" data-slide="prev"> <span class="icon-prev" aria-hidden="true"></span> <span class="sr-only">Previous</span> </a> - <a class="right carousel-control" href="#carousel-example-captions" role="button" data-slide="next"> + <a class="carousel-control carousel-control-right" href="#carouselExampleCaptions" role="button" data-slide="next"> <span class="icon-next" aria-hidden="true"></span> <span class="sr-only">Next</span> </a> @@ -105,25 +163,15 @@ Add captions to your slides easily with the `.carousel-caption` element within a {% highlight html %} <div class="carousel-item"> <img src="..." alt="..."> - <div class="carousel-caption"> + <div class="carousel-caption d-none d-md-block"> <h3>...</h3> <p>...</p> </div> </div> {% endhighlight %} -{% callout danger %} -#### Accessibility issue - -The carousel component is generally not compliant with accessibility standards. If you need to be compliant, please consider other options for presenting your content. -{% endcallout %} - ## Usage -### Multiple carousels - -Carousels require the use of an `id` on the outermost container (the `.carousel`) for carousel controls to function properly. When adding multiple carousels, or when changing a carousel's `id`, be sure to update the relevant controls. - ### Via data attributes Use data attributes to easily control the position of the carousel. `data-slide` accepts the keywords `prev` or `next`, which alters the slide position relative to its current position. Alternatively, use `data-slide-to` to pass a raw slide index to the carousel `data-slide-to="2"`, which shifts the slide position to a particular index beginning with `0`. diff --git a/docs/examples/carousel/carousel.css b/docs/examples/carousel/carousel.css index a1ec54fa5..58fdde1cb 100644 --- a/docs/examples/carousel/carousel.css +++ b/docs/examples/carousel/carousel.css @@ -19,6 +19,7 @@ body { /* Since positioning the image, we need to help out the caption */ .carousel-caption { z-index: 10; + bottom: 3rem; } /* Declare heights because of positioning of img element */ @@ -34,17 +35,12 @@ body { height: 32rem; } -.carousel-indicators { - top: 1.5rem; - right: 1.5rem; - bottom: auto; - left: auto; - width: 1rem; - margin-left: 0; -} - -.carousel-indicators > li { - margin-bottom: .25rem; +.carousel-indicators li { + width: .75rem; + height: .75rem; + margin-right: .25rem; + margin-left: .25rem; + border-radius: 50%; } diff --git a/docs/examples/carousel/index.html b/docs/examples/carousel/index.html index 990553b97..edab89919 100644 --- a/docs/examples/carousel/index.html +++ b/docs/examples/carousel/index.html @@ -37,11 +37,7 @@ </ul> </nav> - - <!-- Carousel - ================================================== --> <div id="myCarousel" class="carousel slide" data-ride="carousel"> - <!-- Indicators --> <ol class="carousel-indicators"> <li data-target="#myCarousel" data-slide-to="0" class="active"></li> <li data-target="#myCarousel" data-slide-to="1"></li> @@ -51,7 +47,7 @@ <div class="carousel-item active"> <img class="first-slide" src="data:image/gif;base64,R0lGODlhAQABAIAAAHd3dwAAACH5BAAAAAAALAAAAAABAAEAAAICRAEAOw==" alt="First slide"> <div class="container"> - <div class="carousel-caption text-left"> + <div class="carousel-caption d-none d-md-block text-left"> <h1>Example headline.</h1> <p>Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec id elit non mi porta gravida at eget metus. Nullam id dolor id nibh ultricies vehicula ut id elit.</p> <p><a class="btn btn-lg btn-primary" href="#" role="button">Sign up today</a></p> @@ -61,7 +57,7 @@ <div class="carousel-item"> <img class="second-slide" src="data:image/gif;base64,R0lGODlhAQABAIAAAHd3dwAAACH5BAAAAAAALAAAAAABAAEAAAICRAEAOw==" alt="Second slide"> <div class="container"> - <div class="carousel-caption"> + <div class="carousel-caption d-none d-md-block"> <h1>Another example headline.</h1> <p>Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec id elit non mi porta gravida at eget metus. Nullam id dolor id nibh ultricies vehicula ut id elit.</p> <p><a class="btn btn-lg btn-primary" href="#" role="button">Learn more</a></p> @@ -71,7 +67,7 @@ <div class="carousel-item"> <img class="third-slide" src="data:image/gif;base64,R0lGODlhAQABAIAAAHd3dwAAACH5BAAAAAAALAAAAAABAAEAAAICRAEAOw==" alt="Third slide"> <div class="container"> - <div class="carousel-caption text-right"> + <div class="carousel-caption d-none d-md-block text-right"> <h1>One more for good measure.</h1> <p>Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec id elit non mi porta gravida at eget metus. Nullam id dolor id nibh ultricies vehicula ut id elit.</p> <p><a class="btn btn-lg btn-primary" href="#" role="button">Browse gallery</a></p> @@ -79,15 +75,15 @@ </div> </div> </div> - <a class="left carousel-control" href="#myCarousel" role="button" data-slide="prev"> - <span class="glyphicon glyphicon-chevron-left" aria-hidden="true"></span> + <a class="carousel-control-prev" href="#myCarousel" role="button" data-slide="prev"> + <span class="carousel-control-prev-icon" aria-hidden="true"></span> <span class="sr-only">Previous</span> </a> - <a class="right carousel-control" href="#myCarousel" role="button" data-slide="next"> - <span class="glyphicon glyphicon-chevron-right" aria-hidden="true"></span> + <a class="carousel-control-next" href="#myCarousel" role="button" data-slide="next"> + <span class="carousel-control-next-icon" aria-hidden="true"></span> <span class="sr-only">Next</span> </a> - </div><!-- /.carousel --> + </div> <!-- Marketing messaging and featurettes diff --git a/docs/migration.md b/docs/migration.md index 9b6e006c7..b6704a669 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -183,7 +183,14 @@ Dropped entirely for the new card component. ### Carousel -- Renamed `.item` to `.carousel-item`. +- Overhauled the entire component to simplify design and styling. We have fewer styles for you to override, new indicators, and new icons. +- All CSS has been un-nested and renamed, ensuring each class is prefixed with `.carousel-`. + - For carousel items, `.next`, `.prev`, `.left`, and `.right` are now `.carousel-item-next`, `.carousel-item-prev`, `.carousel-item-left`, and `.carousel-item-right`. + - `.item` is also now `.carousel-item`. + - For prev/next controls, `.carousel-control.right` and `.carousel-control.left` are now `.carousel-control-right` and `.carousel-control-left`, meaning they no longer require a specific base class. +- Removed all responsive styling, deferring to utilities (e.g., showing captions on certain viewports) and custom styles as needed. +- Removed image overrides for images in carousel items, deferring to utilities. +- Tweaked the Carousel example to include the new markup and styles. ### Utilities |