]>
Commit | Line | Data |
---|---|---|
91e44d91 S |
1 | --- |
2 | layout: docs | |
3 | title: Carousel | |
4 | description: A slideshow component for cycling through elements—images or slides of text—like a carousel. | |
5 | group: components | |
6 | --- | |
7 | ||
8 | 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. | |
9 | ||
10 | 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.). | |
11 | ||
12 | Please be aware that nested carousels are not supported, and carousels are generally not compliant with accessibility standards. | |
13 | ||
14 | ## Contents | |
15 | ||
16 | * Will be replaced with the ToC, excluding the "Contents" header | |
17 | {:toc} | |
18 | ||
19 | ## Example | |
20 | ||
21 | 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. | |
22 | ||
23 | Be sure to set a unique id on the `.carousel` for optional controls, especially if you're using multiple carousels on a single page. | |
24 | ||
25 | ### Slides only | |
26 | ||
27 | 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. | |
28 | ||
29 | {% example html %} | |
30 | <div id="carouselExampleSlidesOnly" class="carousel slide" data-ride="carousel"> | |
31 | <div class="carousel-inner" role="listbox"> | |
32 | <div class="carousel-item active"> | |
33 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> | |
34 | </div> | |
35 | <div class="carousel-item"> | |
36 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> | |
37 | </div> | |
38 | <div class="carousel-item"> | |
39 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> | |
40 | </div> | |
41 | </div> | |
42 | </div> | |
43 | {% endexample %} | |
44 | ||
45 | ### With controls | |
46 | ||
47 | Adding in the previous and next controls: | |
48 | ||
49 | {% example html %} | |
50 | <div id="carouselExampleControls" class="carousel slide" data-ride="carousel"> | |
51 | <div class="carousel-inner" role="listbox"> | |
52 | <div class="carousel-item active"> | |
53 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> | |
54 | </div> | |
55 | <div class="carousel-item"> | |
56 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> | |
57 | </div> | |
58 | <div class="carousel-item"> | |
59 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> | |
60 | </div> | |
61 | </div> | |
62 | <a class="carousel-control-prev" href="#carouselExampleControls" role="button" data-slide="prev"> | |
63 | <span class="carousel-control-prev-icon" aria-hidden="true"></span> | |
64 | <span class="sr-only">Previous</span> | |
65 | </a> | |
66 | <a class="carousel-control-next" href="#carouselExampleControls" role="button" data-slide="next"> | |
67 | <span class="carousel-control-next-icon" aria-hidden="true"></span> | |
68 | <span class="sr-only">Next</span> | |
69 | </a> | |
70 | </div> | |
71 | {% endexample %} | |
72 | ||
73 | ### With indicators | |
74 | ||
75 | You can also add the indicators to the carousel, alongside the controls, too. | |
76 | ||
77 | {% example html %} | |
78 | <div id="carouselExampleIndicators" class="carousel slide" data-ride="carousel"> | |
79 | <ol class="carousel-indicators"> | |
80 | <li data-target="#carouselExampleIndicators" data-slide-to="0" class="active"></li> | |
81 | <li data-target="#carouselExampleIndicators" data-slide-to="1"></li> | |
82 | <li data-target="#carouselExampleIndicators" data-slide-to="2"></li> | |
83 | </ol> | |
84 | <div class="carousel-inner" role="listbox"> | |
85 | <div class="carousel-item active"> | |
86 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> | |
87 | </div> | |
88 | <div class="carousel-item"> | |
89 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> | |
90 | </div> | |
91 | <div class="carousel-item"> | |
92 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> | |
93 | </div> | |
94 | </div> | |
95 | <a class="carousel-control-prev" href="#carouselExampleIndicators" role="button" data-slide="prev"> | |
96 | <span class="carousel-control-prev-icon" aria-hidden="true"></span> | |
97 | <span class="sr-only">Previous</span> | |
98 | </a> | |
99 | <a class="carousel-control-next" href="#carouselExampleIndicators" role="button" data-slide="next"> | |
100 | <span class="carousel-control-next-icon" aria-hidden="true"></span> | |
101 | <span class="sr-only">Next</span> | |
102 | </a> | |
103 | </div> | |
104 | {% endexample %} | |
105 | ||
106 | {% callout warning %} | |
107 | #### Initial active element required | |
108 | ||
109 | The `.active` class needs to be added to one of the slides. Otherwise, the carousel will not be visible. | |
110 | {% endcallout %} | |
111 | ||
112 | ### With captions | |
113 | ||
114 | 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`. | |
115 | ||
116 | <div class="bd-example"> | |
117 | <div id="carouselExampleCaptions" class="carousel slide" data-ride="carousel"> | |
118 | <ol class="carousel-indicators"> | |
119 | <li data-target="#carouselExampleCaptions" data-slide-to="0" class="active"></li> | |
120 | <li data-target="#carouselExampleCaptions" data-slide-to="1"></li> | |
121 | <li data-target="#carouselExampleCaptions" data-slide-to="2"></li> | |
122 | </ol> | |
123 | <div class="carousel-inner" role="listbox"> | |
124 | <div class="carousel-item active"> | |
125 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=777&fg=555&text=First slide" alt="First slide"> | |
126 | <div class="carousel-caption d-none d-md-block"> | |
127 | <h3>First slide label</h3> | |
128 | <p>Nulla vitae elit libero, a pharetra augue mollis interdum.</p> | |
129 | </div> | |
130 | </div> | |
131 | <div class="carousel-item"> | |
132 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=666&fg=444&text=Second slide" alt="Second slide"> | |
133 | <div class="carousel-caption d-none d-md-block"> | |
134 | <h3>Second slide label</h3> | |
135 | <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> | |
136 | </div> | |
137 | </div> | |
138 | <div class="carousel-item"> | |
139 | <img class="d-block img-fluid" data-src="holder.js/800x400?auto=yes&bg=555&fg=333&text=Third slide" alt="Third slide"> | |
140 | <div class="carousel-caption d-none d-md-block"> | |
141 | <h3>Third slide label</h3> | |
142 | <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur.</p> | |
143 | </div> | |
144 | </div> | |
145 | </div> | |
146 | <a class="carousel-control-prev" href="#carouselExampleCaptions" role="button" data-slide="prev"> | |
147 | <span class="carousel-control-prev-icon" aria-hidden="true"></span> | |
148 | <span class="sr-only">Previous</span> | |
149 | </a> | |
150 | <a class="carousel-control-next" href="#carouselExampleCaptions" role="button" data-slide="next"> | |
151 | <span class="carousel-control-next-icon" aria-hidden="true"></span> | |
152 | <span class="sr-only">Next</span> | |
153 | </a> | |
154 | </div> | |
155 | </div> | |
156 | ||
157 | {% highlight html %} | |
158 | <div class="carousel-item"> | |
159 | <img src="..." alt="..."> | |
160 | <div class="carousel-caption d-none d-md-block"> | |
161 | <h3>...</h3> | |
162 | <p>...</p> | |
163 | </div> | |
164 | </div> | |
165 | {% endhighlight %} | |
166 | ||
167 | ## Usage | |
168 | ||
169 | ### Via data attributes | |
170 | ||
171 | 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`. | |
172 | ||
173 | The `data-ride="carousel"` attribute is used to mark a carousel as animating starting at page load. **It cannot be used in combination with (redundant and unnecessary) explicit JavaScript initialization of the same carousel.** | |
174 | ||
175 | ### Via JavaScript | |
176 | ||
177 | Call carousel manually with: | |
178 | ||
179 | {% highlight js %} | |
180 | $('.carousel').carousel() | |
181 | {% endhighlight %} | |
182 | ||
183 | ### Options | |
184 | ||
185 | Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-interval=""`. | |
186 | ||
187 | <table class="table table-bordered table-striped table-responsive"> | |
188 | <thead> | |
189 | <tr> | |
190 | <th style="width: 100px;">Name</th> | |
191 | <th style="width: 50px;">Type</th> | |
192 | <th style="width: 50px;">Default</th> | |
193 | <th>Description</th> | |
194 | </tr> | |
195 | </thead> | |
196 | <tbody> | |
197 | <tr> | |
198 | <td>interval</td> | |
199 | <td>number</td> | |
200 | <td>5000</td> | |
201 | <td>The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.</td> | |
202 | </tr> | |
203 | <tr> | |
204 | <td>keyboard</td> | |
205 | <td>boolean</td> | |
206 | <td>true</td> | |
207 | <td>Whether the carousel should react to keyboard events.</td> | |
208 | </tr> | |
209 | <tr> | |
210 | <td>pause</td> | |
211 | <td>string | null</td> | |
212 | <td>"hover"</td> | |
213 | <td>If set to <code>"hover"</code>, pauses the cycling of the carousel on <code>mouseenter</code> and resumes the cycling of the carousel on <code>mouseleave</code>. If set to <code>null</code>, hovering over the carousel won't pause it.</td> | |
214 | </tr> | |
215 | <tr> | |
216 | <td>ride</td> | |
217 | <td>string</td> | |
218 | <td>false</td> | |
219 | <td>Autoplays the carousel after the user manually cycles the first item. If "carousel", autoplays the carousel on load.</td> | |
220 | </tr> | |
221 | <tr> | |
222 | <td>wrap</td> | |
223 | <td>boolean</td> | |
224 | <td>true</td> | |
225 | <td>Whether the carousel should cycle continuously or have hard stops.</td> | |
226 | </tr> | |
227 | </tbody> | |
228 | </table> | |
229 | ||
230 | ### Methods | |
231 | ||
232 | #### `.carousel(options)` | |
233 | ||
234 | Initializes the carousel with an optional options `object` and starts cycling through items. | |
235 | ||
236 | {% highlight js %} | |
237 | $('.carousel').carousel({ | |
238 | interval: 2000 | |
239 | }) | |
240 | {% endhighlight %} | |
241 | ||
242 | #### `.carousel('cycle')` | |
243 | ||
244 | Cycles through the carousel items from left to right. | |
245 | ||
246 | #### `.carousel('pause')` | |
247 | ||
248 | Stops the carousel from cycling through items. | |
249 | ||
250 | #### `.carousel(number)` | |
251 | ||
252 | Cycles the carousel to a particular frame (0 based, similar to an array). | |
253 | ||
254 | #### `.carousel('prev')` | |
255 | ||
256 | Cycles to the previous item. | |
257 | ||
258 | #### `.carousel('next')` | |
259 | ||
260 | Cycles to the next item. | |
261 | ||
262 | ### Events | |
263 | ||
264 | Bootstrap's carousel class exposes two events for hooking into carousel functionality. Both events have the following additional properties: | |
265 | ||
266 | - `direction`: The direction in which the carousel is sliding (either `"left"` or `"right"`). | |
267 | - `relatedTarget`: The DOM element that is being slid into place as the active item. | |
268 | ||
269 | All carousel events are fired at the carousel itself (i.e. at the `<div class="carousel">`). | |
270 | ||
271 | <table class="table table-bordered table-striped table-responsive"> | |
272 | <thead> | |
273 | <tr> | |
274 | <th style="width: 150px;">Event Type</th> | |
275 | <th>Description</th> | |
276 | </tr> | |
277 | </thead> | |
278 | <tbody> | |
279 | <tr> | |
280 | <td>slide.bs.carousel</td> | |
281 | <td>This event fires immediately when the <code>slide</code> instance method is invoked.</td> | |
282 | </tr> | |
283 | <tr> | |
284 | <td>slid.bs.carousel</td> | |
285 | <td>This event is fired when the carousel has completed its slide transition.</td> | |
286 | </tr> | |
287 | </tbody> | |
288 | </table> | |
289 | ||
290 | {% highlight js %} | |
291 | $('#myCarousel').on('slide.bs.carousel', function () { | |
292 | // do something… | |
293 | }) | |
294 | {% endhighlight %} |