]> git.ipfire.org Git - ipfire.org.git/blame - static/scss/bootstrap-4.0.0-alpha.6/docs/components/dropdowns.md
projects / ipfire.org.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
.gitignore: Add .vscode
[ipfire.org.git] / static / scss / bootstrap-4.0.0-alpha.6 / docs / components / dropdowns.md
CommitLineData
91e44d91
S		 1---
2layout: docs
3title: Dropdowns
4description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin.
5group: components
6---
7
8Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They're made interactive with the included Bootstrap dropdown JavaScript plugin. They're toggled by clicking, not by hovering; this is [an intentional design decision.](http://markdotto.com/2012/02/27/bootstrap-explained-dropdowns/)
9
10## Contents
11
12* Will be replaced with the ToC, excluding the "Contents" header
13{:toc}
14
15## Examples
16
17Wrap the dropdown's toggle (your button or link) and the dropdown menu within `.dropdown`, or another element that declares `position: relative;`. Dropdowns can be triggered from `<a>` or `<button>` elements to better fit your potential needs.
18
19### Single button dropdowns
20
21Any single `.btn` can be turned into a dropdown toggle with some markup changes. Here's how you can put them to work with either `<button>` elements:
22
23{% example html %}
24<div class="dropdown">
25 <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
26 Dropdown button
27 </button>
28 <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
29 <a class="dropdown-item" href="#">Action</a>
30 <a class="dropdown-item" href="#">Another action</a>
31 <a class="dropdown-item" href="#">Something else here</a>
32 </div>
33</div>
34{% endexample %}
35
36And with `<a>` elements:
37
38{% example html %}
39<div class="dropdown show">
40 <a class="btn btn-secondary dropdown-toggle" href="https://example.com" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
41 Dropdown link
42 </a>
43
44 <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
45 <a class="dropdown-item" href="#">Action</a>
46 <a class="dropdown-item" href="#">Another action</a>
47 <a class="dropdown-item" href="#">Something else here</a>
48 </div>
49</div>
50{% endexample %}
51
52The best part is you can do this with any button variant, too:
53
54<div class="bd-example">
55 <div class="btn-group">
56 <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Primary</button>
57 <div class="dropdown-menu">
58 <a class="dropdown-item" href="#">Action</a>
59 <a class="dropdown-item" href="#">Another action</a>
60 <a class="dropdown-item" href="#">Something else here</a>
61 <div class="dropdown-divider"></div>
62 <a class="dropdown-item" href="#">Separated link</a>
63 </div>
64 </div><!-- /btn-group -->
65 <div class="btn-group">
66 <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Secondary</button>
67 <div class="dropdown-menu">
68 <a class="dropdown-item" href="#">Action</a>
69 <a class="dropdown-item" href="#">Another action</a>
70 <a class="dropdown-item" href="#">Something else here</a>
71 <div class="dropdown-divider"></div>
72 <a class="dropdown-item" href="#">Separated link</a>
73 </div>
74 </div><!-- /btn-group -->
75 <div class="btn-group">
76 <button type="button" class="btn btn-success dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Success</button>
77 <div class="dropdown-menu">
78 <a class="dropdown-item" href="#">Action</a>
79 <a class="dropdown-item" href="#">Another action</a>
80 <a class="dropdown-item" href="#">Something else here</a>
81 <div class="dropdown-divider"></div>
82 <a class="dropdown-item" href="#">Separated link</a>
83 </div>
84 </div><!-- /btn-group -->
85 <div class="btn-group">
86 <button type="button" class="btn btn-info dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Info</button>
87 <div class="dropdown-menu">
88 <a class="dropdown-item" href="#">Action</a>
89 <a class="dropdown-item" href="#">Another action</a>
90 <a class="dropdown-item" href="#">Something else here</a>
91 <div class="dropdown-divider"></div>
92 <a class="dropdown-item" href="#">Separated link</a>
93 </div>
94 </div><!-- /btn-group -->
95 <div class="btn-group">
96 <button type="button" class="btn btn-warning dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Warning</button>
97 <div class="dropdown-menu">
98 <a class="dropdown-item" href="#">Action</a>
99 <a class="dropdown-item" href="#">Another action</a>
100 <a class="dropdown-item" href="#">Something else here</a>
101 <div class="dropdown-divider"></div>
102 <a class="dropdown-item" href="#">Separated link</a>
103 </div>
104 </div><!-- /btn-group -->
105 <div class="btn-group">
106 <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Danger</button>
107 <div class="dropdown-menu">
108 <a class="dropdown-item" href="#">Action</a>
109 <a class="dropdown-item" href="#">Another action</a>
110 <a class="dropdown-item" href="#">Something else here</a>
111 <div class="dropdown-divider"></div>
112 <a class="dropdown-item" href="#">Separated link</a>
113 </div>
114 </div><!-- /btn-group -->
115</div>
116
117{% highlight html %}
118<!-- Example single danger button -->
119<div class="btn-group">
120 <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
121 Action
122 </button>
123 <div class="dropdown-menu">
124 <a class="dropdown-item" href="#">Action</a>
125 <a class="dropdown-item" href="#">Another action</a>
126 <a class="dropdown-item" href="#">Something else here</a>
127 <div class="dropdown-divider"></div>
128 <a class="dropdown-item" href="#">Separated link</a>
129 </div>
130</div>
131{% endhighlight %}
132
133### Split button dropdowns
134
135Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of `.dropdown-toggle-split` for proper spacing around the dropdown caret.
136
137We use this extra class to reduce the horizontal `padding` on either side of the caret by 25% and remove the `margin-left` that's added for regular button dropdowns. Those extra changes keep the caret centered in the split button and provide a more appropriately sized hit area next to the main button.
138
139<div class="bd-example">
140 <div class="btn-group">
141 <button type="button" class="btn btn-primary">Primary</button>
142 <button type="button" class="btn btn-primary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
143 <span class="sr-only">Toggle Dropdown</span>
144 </button>
145 <div class="dropdown-menu">
146 <a class="dropdown-item" href="#">Action</a>
147 <a class="dropdown-item" href="#">Another action</a>
148 <a class="dropdown-item" href="#">Something else here</a>
149 <div class="dropdown-divider"></div>
150 <a class="dropdown-item" href="#">Separated link</a>
151 </div>
152 </div><!-- /btn-group -->
153 <div class="btn-group">
154 <button type="button" class="btn btn-secondary">Secondary</button>
155 <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
156 <span class="sr-only">Toggle Dropdown</span>
157 </button>
158 <div class="dropdown-menu">
159 <a class="dropdown-item" href="#">Action</a>
160 <a class="dropdown-item" href="#">Another action</a>
161 <a class="dropdown-item" href="#">Something else here</a>
162 <div class="dropdown-divider"></div>
163 <a class="dropdown-item" href="#">Separated link</a>
164 </div>
165 </div><!-- /btn-group -->
166 <div class="btn-group">
167 <button type="button" class="btn btn-success">Success</button>
168 <button type="button" class="btn btn-success dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
169 <span class="sr-only">Toggle Dropdown</span>
170 </button>
171 <div class="dropdown-menu">
172 <a class="dropdown-item" href="#">Action</a>
173 <a class="dropdown-item" href="#">Another action</a>
174 <a class="dropdown-item" href="#">Something else here</a>
175 <div class="dropdown-divider"></div>
176 <a class="dropdown-item" href="#">Separated link</a>
177 </div>
178 </div><!-- /btn-group -->
179 <div class="btn-group">
180 <button type="button" class="btn btn-info">Info</button>
181 <button type="button" class="btn btn-info dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
182 <span class="sr-only">Toggle Dropdown</span>
183 </button>
184 <div class="dropdown-menu">
185 <a class="dropdown-item" href="#">Action</a>
186 <a class="dropdown-item" href="#">Another action</a>
187 <a class="dropdown-item" href="#">Something else here</a>
188 <div class="dropdown-divider"></div>
189 <a class="dropdown-item" href="#">Separated link</a>
190 </div>
191 </div><!-- /btn-group -->
192 <div class="btn-group">
193 <button type="button" class="btn btn-warning">Warning</button>
194 <button type="button" class="btn btn-warning dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
195 <span class="sr-only">Toggle Dropdown</span>
196 </button>
197 <div class="dropdown-menu">
198 <a class="dropdown-item" href="#">Action</a>
199 <a class="dropdown-item" href="#">Another action</a>
200 <a class="dropdown-item" href="#">Something else here</a>
201 <div class="dropdown-divider"></div>
202 <a class="dropdown-item" href="#">Separated link</a>
203 </div>
204 </div><!-- /btn-group -->
205 <div class="btn-group">
206 <button type="button" class="btn btn-danger">Danger</button>
207 <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
208 <span class="sr-only">Toggle Dropdown</span>
209 </button>
210 <div class="dropdown-menu">
211 <a class="dropdown-item" href="#">Action</a>
212 <a class="dropdown-item" href="#">Another action</a>
213 <a class="dropdown-item" href="#">Something else here</a>
214 <div class="dropdown-divider"></div>
215 <a class="dropdown-item" href="#">Separated link</a>
216 </div>
217 </div><!-- /btn-group -->
218</div>
219
220{% highlight html %}
221<!-- Example split danger button -->
222<div class="btn-group">
223 <button type="button" class="btn btn-danger">Action</button>
224 <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
225 <span class="sr-only">Toggle Dropdown</span>
226 </button>
227 <div class="dropdown-menu">
228 <a class="dropdown-item" href="#">Action</a>
229 <a class="dropdown-item" href="#">Another action</a>
230 <a class="dropdown-item" href="#">Something else here</a>
231 <div class="dropdown-divider"></div>
232 <a class="dropdown-item" href="#">Separated link</a>
233 </div>
234</div>
235{% endhighlight %}
236
237## Sizing
238
239Button dropdowns work with buttons of all sizes, including default and split dropdown buttons.
240
241<div class="bd-example">
242 <div class="btn-toolbar" role="toolbar">
243 <div class="btn-group">
244 <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
245 Large button
246 </button>
247 <div class="dropdown-menu">
248 <a class="dropdown-item" href="#">Action</a>
249 <a class="dropdown-item" href="#">Another action</a>
250 <a class="dropdown-item" href="#">Something else here</a>
251 <div class="dropdown-divider"></div>
252 <a class="dropdown-item" href="#">Separated link</a>
253 </div>
254 </div><!-- /btn-group -->
255 <div class="btn-group ml-2">
256 <button type="button" class="btn btn-lg btn-secondary">Large split button</button>
257 <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
258 <span class="sr-only">Toggle Dropdown</span>
259 </button>
260 <div class="dropdown-menu">
261 <a class="dropdown-item" href="#">Action</a>
262 <a class="dropdown-item" href="#">Another action</a>
263 <a class="dropdown-item" href="#">Something else here</a>
264 <div class="dropdown-divider"></div>
265 <a class="dropdown-item" href="#">Separated link</a>
266 </div>
267 </div><!-- /btn-group -->
268 </div><!-- /btn-toolbar -->
269 <div class="btn-toolbar" role="toolbar">
270 <div class="btn-group">
271 <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
272 Small button
273 </button>
274 <div class="dropdown-menu">
275 <a class="dropdown-item" href="#">Action</a>
276 <a class="dropdown-item" href="#">Another action</a>
277 <a class="dropdown-item" href="#">Something else here</a>
278 <div class="dropdown-divider"></div>
279 <a class="dropdown-item" href="#">Separated link</a>
280 </div>
281 </div><!-- /btn-group -->
282 <div class="btn-group ml-2">
283 <button type="button" class="btn btn-sm btn-secondary">Small split button</button>
284 <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
285 <span class="sr-only">Toggle Dropdown</span>
286 </button>
287 <div class="dropdown-menu">
288 <a class="dropdown-item" href="#">Action</a>
289 <a class="dropdown-item" href="#">Another action</a>
290 <a class="dropdown-item" href="#">Something else here</a>
291 <div class="dropdown-divider"></div>
292 <a class="dropdown-item" href="#">Separated link</a>
293 </div>
294 </div><!-- /btn-group -->
295 </div><!-- /btn-toolbar -->
296</div><!-- /example -->
297
298{% highlight html %}
299<!-- Large button groups (default and split) -->
300<div class="btn-group">
301 <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
302 Large button
303 </button>
304 <div class="dropdown-menu">
305 ...
306 </div>
307</div>
308<div class="btn-group">
309 <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
310 Large button
311 </button>
312 <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
313 <span class="sr-only">Toggle Dropdown</span>
314 </button>
315 <div class="dropdown-menu">
316 ...
317 </div>
318</div>
319
320<!-- Small button groups (default and split) -->
321<div class="btn-group">
322 <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
323 Small button
324 </button>
325 <div class="dropdown-menu">
326 ...
327 </div>
328</div>
329<div class="btn-group">
330 <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
331 Small button
332 </button>
333 <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
334 <span class="sr-only">Toggle Dropdown</span>
335 </button>
336 <div class="dropdown-menu">
337 ...
338 </div>
339</div>
340{% endhighlight %}
341
342## Dropup variation
343
344Trigger dropdown menus above elements by adding `.dropup` to the parent element.
345
346<div class="bd-example">
347 <div class="btn-group dropup">
348 <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
349 Dropup
350 </button>
351 <div class="dropdown-menu">
352 <a class="dropdown-item" href="#">Action</a>
353 <a class="dropdown-item" href="#">Another action</a>
354 <a class="dropdown-item" href="#">Something else here</a>
355 <div class="dropdown-divider"></div>
356 <a class="dropdown-item" href="#">Separated link</a>
357 </div>
358 </div>
359
360 <div class="btn-group dropup">
361 <button type="button" class="btn btn-secondary">
362 Split dropup
363 </button>
364 <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
365 <span class="sr-only">Toggle Dropdown</span>
366 </button>
367 <div class="dropdown-menu">
368 <a class="dropdown-item" href="#">Action</a>
369 <a class="dropdown-item" href="#">Another action</a>
370 <a class="dropdown-item" href="#">Something else here</a>
371 <div class="dropdown-divider"></div>
372 <a class="dropdown-item" href="#">Separated link</a>
373 </div>
374 </div>
375</div>
376
377{% highlight html %}
378<!-- Default dropup button -->
379<div class="btn-group dropup">
380 <button type="button" class="btn btn-secondary">Dropup</button>
381 <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
382 <span class="sr-only">Toggle Dropdown</span>
383 </button>
384 <div class="dropdown-menu">
385 <!-- Dropdown menu links -->
386 </div>
387</div>
388
389<!-- Split dropup button -->
390<div class="btn-group dropup">
391 <button type="button" class="btn btn-secondary">
392 Split dropup
393 </button>
394 <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
395 <span class="sr-only">Toggle Dropdown</span>
396 </button>
397 <div class="dropdown-menu">
398 <!-- Dropdown menu links -->
399 </div>
400</div>
401{% endhighlight %}
402
403## Menu items
404
405Historically dropdown menu contents *had* to be links, but that's no longer the case with v4. Now you can optionally use `<button>` elements in your dropdowns instead of just `<a>`s.
406
407{% example html %}
408<div class="dropdown">
409 <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
410 Dropdown
411 </button>
412 <div class="dropdown-menu" aria-labelledby="dropdownMenu2">
413 <button class="dropdown-item" type="button">Action</button>
414 <button class="dropdown-item" type="button">Another action</button>
415 <button class="dropdown-item" type="button">Something else here</button>
416 </div>
417</div>
418{% endexample %}
419
420## Menu alignment
421
422By default, a dropdown menu is automatically positioned 100% from the top and along the left side of its parent. Add `.dropdown-menu-right` to a `.dropdown-menu` to right align the dropdown menu.
423
424{% callout info %}
425**Heads up!** Dropdowns are positioned only with CSS and may need some additional styles for exact alignment.
426{% endcallout %}
427
428{% example html %}
429<div class="btn-group">
430 <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
431 This dropdown's menu is right-aligned
432 </button>
433 <div class="dropdown-menu dropdown-menu-right">
434 <button class="dropdown-item" type="button">Action</button>
435 <button class="dropdown-item" type="button">Another action</button>
436 <button class="dropdown-item" type="button">Something else here</button>
437 </div>
438</div>
439{% endexample %}
440
441## Menu headers
442
443Add a header to label sections of actions in any dropdown menu.
444
445{% example html %}
446<div class="dropdown-menu">
447 <h6 class="dropdown-header">Dropdown header</h6>
448 <a class="dropdown-item" href="#">Action</a>
449 <a class="dropdown-item" href="#">Another action</a>
450</div>
451{% endexample %}
452
453## Menu dividers
454
455Separate groups of related menu items with a divider.
456
457{% example html %}
458<div class="dropdown-menu">
459 <a class="dropdown-item" href="#">Action</a>
460 <a class="dropdown-item" href="#">Another action</a>
461 <a class="dropdown-item" href="#">Something else here</a>
462 <div class="dropdown-divider"></div>
463 <a class="dropdown-item" href="#">Separated link</a>
464</div>
465{% endexample %}
466
467## Disabled menu items
468
469Add `.disabled` to items in the dropdown to **style them as disabled**.
470
471{% example html %}
472<div class="dropdown-menu">
473 <a class="dropdown-item" href="#">Regular link</a>
474 <a class="dropdown-item disabled" href="#">Disabled link</a>
475 <a class="dropdown-item" href="#">Another link</a>
476</div>
477{% endexample %}
478
479## Usage
480
481Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the `.show` class on the parent list item.
482
483On mobile devices, opening a dropdown adds a `.dropdown-backdrop` as a tap area for closing dropdown menus when tapping outside the menu, a requirement for proper iOS support. **This means that switching from an open dropdown menu to a different dropdown menu requires an extra tap on mobile.**
484
485Note: The `data-toggle="dropdown"` attribute is relied on for closing dropdown menus at an application level, so it's a good idea to always use it.
486
487### Via data attributes
488
489Add `data-toggle="dropdown"` to a link or button to toggle a dropdown.
490
491{% highlight html %}
492<div class="dropdown">
493 <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
494 Dropdown trigger
495 </button>
496 <div class="dropdown-menu" aria-labelledby="dLabel">
497 ...
498 </div>
499</div>
500{% endhighlight %}
501
502### Via JavaScript
503
504Call the dropdowns via JavaScript:
505
506{% highlight js %}
507$('.dropdown-toggle').dropdown()
508{% endhighlight %}
509
510{% callout info %}
511##### `data-toggle="dropdown"` still required
512
513Regardless of whether you call your dropdown via JavaScript or instead use the data-api, `data-toggle="dropdown"` is always required to be present on the dropdown's trigger element.
514{% endcallout %}
515
516### Options
517
518*None.*
519
520### Methods
521
522| Method | Description |
523| --- | --- |
524| `$().dropdown('toggle')` | Toggles the dropdown menu of a given navbar or tabbed navigation. |
525
526### Events
527
528All dropdown events are fired at the `.dropdown-menu`'s parent element and have a `relatedTarget` property, whose value is the toggling anchor element.
529
530| Event | Description |
531| --- | --- |
532| `show.bs.dropdown` | This event fires immediately when the show instance method is called. |
533| `shown.bs.dropdown` | This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete). |
534| `hide.bs.dropdown` | This event is fired immediately when the hide instance method has been called. |
535| `hidden.bs.dropdown`| This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete). |
536
537{% highlight js %}
538$('#myDropdown').on('show.bs.dropdown', function () {
539 // do something…
540})
541{% endhighlight %}
The website of ipfire.org.