Stripped personal data from development repository
view | history | commit | commitdiff
Samo Penic
2019-02-20 83c3f647c35477564b77cbc5b36d37d793d5442a
commit | author | age
83c3f6 1 ---
SP 2 layout: docs
3 title: Dropdowns
4 description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin.
5 group: components
6 toc: true
7 ---
8
9 ## Overview
10
11 Dropdowns 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/).
12
13 Dropdowns are built on a third party library, [Popper.js](https://popper.js.org/), which provides dynamic positioning and viewport detection. Be sure to include [popper.min.js]({{ site.cdn.popper }}) before Bootstrap's JavaScript or use `bootstrap.bundle.min.js` / `bootstrap.bundle.js` which contains Popper.js. Popper.js isn't used to position dropdowns in navbars though as dynamic positioning isn't required.
14
15 If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
16
17 ## Accessibility
18
19 The [<abbr title="Web Accessibility Initiative">WAI</abbr> <abbr title="Accessible Rich Internet Applications">ARIA</abbr>](https://www.w3.org/TR/wai-aria/) standard defines an actual [`role="menu"` widget](https://www.w3.org/WAI/PF/aria/roles#menu), but this is specific to application-like menus which trigger actions or functions. <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus can only contain menu items, checkbox menu items, radio button menu items, radio button groups, and sub-menus.
20
21 Bootstrap's dropdowns, on the other hand, are designed to be generic and applicable to a variety of situations and markup structures. For instance, it is possible to create dropdowns that contain additional inputs and form controls, such as search fields or login forms. For this reason, Bootstrap does not expect (nor automatically add) any of the `role` and `aria-` attributes required for true <abbr title="Accessible Rich Internet Applications">ARIA</abbr> menus. Authors will have to include these more specific attributes themselves.
22
23 However, Bootstrap does add built-in support for most standard keyboard menu interactions, such as the ability to move through individual `.dropdown-item` elements using the cursor keys and close the menu with the <kbd>ESC</kbd> key.
24
25 ## Examples
26
27 Wrap 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.
28
29 ### Single button
30
31 Any 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:
32
33 {% capture example %}
34 <div class="dropdown">
35   <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
36     Dropdown button
37   </button>
38   <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
39     <a class="dropdown-item" href="#">Action</a>
40     <a class="dropdown-item" href="#">Another action</a>
41     <a class="dropdown-item" href="#">Something else here</a>
42   </div>
43 </div>
44 {% endcapture %}
45 {% include example.html content=example %}
46
47 And with `<a>` elements:
48
49 {% capture example %}
50 <div class="dropdown">
51   <a class="btn btn-secondary dropdown-toggle" href="#" role="button" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
52     Dropdown link
53   </a>
54
55   <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
56     <a class="dropdown-item" href="#">Action</a>
57     <a class="dropdown-item" href="#">Another action</a>
58     <a class="dropdown-item" href="#">Something else here</a>
59   </div>
60 </div>
61 {% endcapture %}
62 {% include example.html content=example %}
63
64 The best part is you can do this with any button variant, too:
65
66 <div class="bd-example">
67   <div class="btn-group">
68     <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Primary</button>
69     <div class="dropdown-menu">
70       <a class="dropdown-item" href="#">Action</a>
71       <a class="dropdown-item" href="#">Another action</a>
72       <a class="dropdown-item" href="#">Something else here</a>
73       <div class="dropdown-divider"></div>
74       <a class="dropdown-item" href="#">Separated link</a>
75     </div>
76   </div><!-- /btn-group -->
77   <div class="btn-group">
78     <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Secondary</button>
79     <div class="dropdown-menu">
80       <a class="dropdown-item" href="#">Action</a>
81       <a class="dropdown-item" href="#">Another action</a>
82       <a class="dropdown-item" href="#">Something else here</a>
83       <div class="dropdown-divider"></div>
84       <a class="dropdown-item" href="#">Separated link</a>
85     </div>
86   </div><!-- /btn-group -->
87   <div class="btn-group">
88     <button type="button" class="btn btn-success dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Success</button>
89     <div class="dropdown-menu">
90       <a class="dropdown-item" href="#">Action</a>
91       <a class="dropdown-item" href="#">Another action</a>
92       <a class="dropdown-item" href="#">Something else here</a>
93       <div class="dropdown-divider"></div>
94       <a class="dropdown-item" href="#">Separated link</a>
95     </div>
96   </div><!-- /btn-group -->
97   <div class="btn-group">
98     <button type="button" class="btn btn-info dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Info</button>
99     <div class="dropdown-menu">
100       <a class="dropdown-item" href="#">Action</a>
101       <a class="dropdown-item" href="#">Another action</a>
102       <a class="dropdown-item" href="#">Something else here</a>
103       <div class="dropdown-divider"></div>
104       <a class="dropdown-item" href="#">Separated link</a>
105     </div>
106   </div><!-- /btn-group -->
107   <div class="btn-group">
108     <button type="button" class="btn btn-warning dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Warning</button>
109     <div class="dropdown-menu">
110       <a class="dropdown-item" href="#">Action</a>
111       <a class="dropdown-item" href="#">Another action</a>
112       <a class="dropdown-item" href="#">Something else here</a>
113       <div class="dropdown-divider"></div>
114       <a class="dropdown-item" href="#">Separated link</a>
115     </div>
116   </div><!-- /btn-group -->
117   <div class="btn-group">
118     <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Danger</button>
119     <div class="dropdown-menu">
120       <a class="dropdown-item" href="#">Action</a>
121       <a class="dropdown-item" href="#">Another action</a>
122       <a class="dropdown-item" href="#">Something else here</a>
123       <div class="dropdown-divider"></div>
124       <a class="dropdown-item" href="#">Separated link</a>
125     </div>
126   </div><!-- /btn-group -->
127 </div>
128
129 {% highlight html %}
130 <!-- Example single danger button -->
131 <div class="btn-group">
132   <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
133     Action
134   </button>
135   <div class="dropdown-menu">
136     <a class="dropdown-item" href="#">Action</a>
137     <a class="dropdown-item" href="#">Another action</a>
138     <a class="dropdown-item" href="#">Something else here</a>
139     <div class="dropdown-divider"></div>
140     <a class="dropdown-item" href="#">Separated link</a>
141   </div>
142 </div>
143 {% endhighlight %}
144
145 ### Split button
146
147 Similarly, 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.
148
149 We 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.
150
151 <div class="bd-example">
152   <div class="btn-group">
153     <button type="button" class="btn btn-primary">Primary</button>
154     <button type="button" class="btn btn-primary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
155       <span class="sr-only">Toggle Dropdown</span>
156     </button>
157     <div class="dropdown-menu">
158       <a class="dropdown-item" href="#">Action</a>
159       <a class="dropdown-item" href="#">Another action</a>
160       <a class="dropdown-item" href="#">Something else here</a>
161       <div class="dropdown-divider"></div>
162       <a class="dropdown-item" href="#">Separated link</a>
163     </div>
164   </div><!-- /btn-group -->
165   <div class="btn-group">
166     <button type="button" class="btn btn-secondary">Secondary</button>
167     <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
168       <span class="sr-only">Toggle Dropdown</span>
169     </button>
170     <div class="dropdown-menu">
171       <a class="dropdown-item" href="#">Action</a>
172       <a class="dropdown-item" href="#">Another action</a>
173       <a class="dropdown-item" href="#">Something else here</a>
174       <div class="dropdown-divider"></div>
175       <a class="dropdown-item" href="#">Separated link</a>
176     </div>
177   </div><!-- /btn-group -->
178   <div class="btn-group">
179     <button type="button" class="btn btn-success">Success</button>
180     <button type="button" class="btn btn-success dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
181       <span class="sr-only">Toggle Dropdown</span>
182     </button>
183     <div class="dropdown-menu">
184       <a class="dropdown-item" href="#">Action</a>
185       <a class="dropdown-item" href="#">Another action</a>
186       <a class="dropdown-item" href="#">Something else here</a>
187       <div class="dropdown-divider"></div>
188       <a class="dropdown-item" href="#">Separated link</a>
189     </div>
190   </div><!-- /btn-group -->
191   <div class="btn-group">
192     <button type="button" class="btn btn-info">Info</button>
193     <button type="button" class="btn btn-info dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
194       <span class="sr-only">Toggle Dropdown</span>
195     </button>
196     <div class="dropdown-menu">
197       <a class="dropdown-item" href="#">Action</a>
198       <a class="dropdown-item" href="#">Another action</a>
199       <a class="dropdown-item" href="#">Something else here</a>
200       <div class="dropdown-divider"></div>
201       <a class="dropdown-item" href="#">Separated link</a>
202     </div>
203   </div><!-- /btn-group -->
204   <div class="btn-group">
205     <button type="button" class="btn btn-warning">Warning</button>
206     <button type="button" class="btn btn-warning dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
207       <span class="sr-only">Toggle Dropdown</span>
208     </button>
209     <div class="dropdown-menu">
210       <a class="dropdown-item" href="#">Action</a>
211       <a class="dropdown-item" href="#">Another action</a>
212       <a class="dropdown-item" href="#">Something else here</a>
213       <div class="dropdown-divider"></div>
214       <a class="dropdown-item" href="#">Separated link</a>
215     </div>
216   </div><!-- /btn-group -->
217   <div class="btn-group">
218     <button type="button" class="btn btn-danger">Danger</button>
219     <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
220       <span class="sr-only">Toggle Dropdown</span>
221     </button>
222     <div class="dropdown-menu">
223       <a class="dropdown-item" href="#">Action</a>
224       <a class="dropdown-item" href="#">Another action</a>
225       <a class="dropdown-item" href="#">Something else here</a>
226       <div class="dropdown-divider"></div>
227       <a class="dropdown-item" href="#">Separated link</a>
228     </div>
229   </div><!-- /btn-group -->
230 </div>
231
232 {% highlight html %}
233 <!-- Example split danger button -->
234 <div class="btn-group">
235   <button type="button" class="btn btn-danger">Action</button>
236   <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
237     <span class="sr-only">Toggle Dropdown</span>
238   </button>
239   <div class="dropdown-menu">
240     <a class="dropdown-item" href="#">Action</a>
241     <a class="dropdown-item" href="#">Another action</a>
242     <a class="dropdown-item" href="#">Something else here</a>
243     <div class="dropdown-divider"></div>
244     <a class="dropdown-item" href="#">Separated link</a>
245   </div>
246 </div>
247 {% endhighlight %}
248
249 ## Sizing
250
251 Button dropdowns work with buttons of all sizes, including default and split dropdown buttons.
252
253 <div class="bd-example">
254   <div class="btn-toolbar" role="toolbar">
255     <div class="btn-group">
256       <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
257         Large button
258       </button>
259       <div class="dropdown-menu">
260         <a class="dropdown-item" href="#">Action</a>
261         <a class="dropdown-item" href="#">Another action</a>
262         <a class="dropdown-item" href="#">Something else here</a>
263         <div class="dropdown-divider"></div>
264         <a class="dropdown-item" href="#">Separated link</a>
265       </div>
266     </div><!-- /btn-group -->
267     <div class="btn-group ml-2">
268       <button type="button" class="btn btn-lg btn-secondary">Large split button</button>
269       <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
270         <span class="sr-only">Toggle Dropdown</span>
271       </button>
272       <div class="dropdown-menu">
273         <a class="dropdown-item" href="#">Action</a>
274         <a class="dropdown-item" href="#">Another action</a>
275         <a class="dropdown-item" href="#">Something else here</a>
276         <div class="dropdown-divider"></div>
277         <a class="dropdown-item" href="#">Separated link</a>
278       </div>
279     </div><!-- /btn-group -->
280   </div><!-- /btn-toolbar -->
281   <div class="btn-toolbar" role="toolbar">
282     <div class="btn-group">
283       <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
284         Small button
285       </button>
286       <div class="dropdown-menu">
287         <a class="dropdown-item" href="#">Action</a>
288         <a class="dropdown-item" href="#">Another action</a>
289         <a class="dropdown-item" href="#">Something else here</a>
290         <div class="dropdown-divider"></div>
291         <a class="dropdown-item" href="#">Separated link</a>
292       </div>
293     </div><!-- /btn-group -->
294     <div class="btn-group ml-2">
295       <button type="button" class="btn btn-sm btn-secondary">Small split button</button>
296       <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
297         <span class="sr-only">Toggle Dropdown</span>
298       </button>
299       <div class="dropdown-menu">
300         <a class="dropdown-item" href="#">Action</a>
301         <a class="dropdown-item" href="#">Another action</a>
302         <a class="dropdown-item" href="#">Something else here</a>
303         <div class="dropdown-divider"></div>
304         <a class="dropdown-item" href="#">Separated link</a>
305       </div>
306     </div><!-- /btn-group -->
307   </div><!-- /btn-toolbar -->
308 </div><!-- /example -->
309
310 {% highlight html %}
311 <!-- Large button groups (default and split) -->
312 <div class="btn-group">
313   <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
314     Large button
315   </button>
316   <div class="dropdown-menu">
317     ...
318   </div>
319 </div>
320 <div class="btn-group">
321   <button class="btn btn-secondary btn-lg" type="button">
322     Large split button
323   </button>
324   <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
325     <span class="sr-only">Toggle Dropdown</span>
326   </button>
327   <div class="dropdown-menu">
328     ...
329   </div>
330 </div>
331
332 <!-- Small button groups (default and split) -->
333 <div class="btn-group">
334   <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
335     Small button
336   </button>
337   <div class="dropdown-menu">
338     ...
339   </div>
340 </div>
341 <div class="btn-group">
342   <button class="btn btn-secondary btn-sm" type="button">
343     Small split button
344   </button>
345   <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
346     <span class="sr-only">Toggle Dropdown</span>
347   </button>
348   <div class="dropdown-menu">
349     ...
350   </div>
351 </div>
352 {% endhighlight %}
353
354 ## Directions
355
356 ### Dropup
357
358 Trigger dropdown menus above elements by adding `.dropup` to the parent element.
359
360 <div class="bd-example">
361   <div class="btn-group dropup">
362     <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
363       Dropup
364     </button>
365     <div class="dropdown-menu">
366       <a class="dropdown-item" href="#">Action</a>
367       <a class="dropdown-item" href="#">Another action</a>
368       <a class="dropdown-item" href="#">Something else here</a>
369       <div class="dropdown-divider"></div>
370       <a class="dropdown-item" href="#">Separated link</a>
371     </div>
372   </div>
373
374   <div class="btn-group dropup">
375     <button type="button" class="btn btn-secondary">
376       Split dropup
377     </button>
378     <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
379       <span class="sr-only">Toggle Dropdown</span>
380     </button>
381     <div class="dropdown-menu">
382       <a class="dropdown-item" href="#">Action</a>
383       <a class="dropdown-item" href="#">Another action</a>
384       <a class="dropdown-item" href="#">Something else here</a>
385       <div class="dropdown-divider"></div>
386       <a class="dropdown-item" href="#">Separated link</a>
387     </div>
388   </div>
389 </div>
390
391 {% highlight html %}
392 <!-- Default dropup button -->
393 <div class="btn-group dropup">
394   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
395     Dropup
396   </button>
397   <div class="dropdown-menu">
398     <!-- Dropdown menu links -->
399   </div>
400 </div>
401
402 <!-- Split dropup button -->
403 <div class="btn-group dropup">
404   <button type="button" class="btn btn-secondary">
405     Split dropup
406   </button>
407   <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
408     <span class="sr-only">Toggle Dropdown</span>
409   </button>
410   <div class="dropdown-menu">
411     <!-- Dropdown menu links -->
412   </div>
413 </div>
414 {% endhighlight %}
415
416 ### Dropright
417
418 Trigger dropdown menus at the right of the elements by adding `.dropright` to the parent element.
419
420 <div class="bd-example">
421   <div class="btn-group dropright">
422     <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
423       Dropright
424     </button>
425     <div class="dropdown-menu">
426       <a class="dropdown-item" href="#">Action</a>
427       <a class="dropdown-item" href="#">Another action</a>
428       <a class="dropdown-item" href="#">Something else here</a>
429       <div class="dropdown-divider"></div>
430       <a class="dropdown-item" href="#">Separated link</a>
431     </div>
432   </div>
433
434   <div class="btn-group dropright">
435     <button type="button" class="btn btn-secondary">
436       Split dropright
437     </button>
438     <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
439       <span class="sr-only">Toggle Dropright</span>
440     </button>
441     <div class="dropdown-menu">
442       <a class="dropdown-item" href="#">Action</a>
443       <a class="dropdown-item" href="#">Another action</a>
444       <a class="dropdown-item" href="#">Something else here</a>
445       <div class="dropdown-divider"></div>
446       <a class="dropdown-item" href="#">Separated link</a>
447     </div>
448   </div>
449 </div>
450
451 {% highlight html %}
452 <!-- Default dropright button -->
453 <div class="btn-group dropright">
454   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
455     Dropright
456   </button>
457   <div class="dropdown-menu">
458     <!-- Dropdown menu links -->
459   </div>
460 </div>
461
462 <!-- Split dropright button -->
463 <div class="btn-group dropright">
464   <button type="button" class="btn btn-secondary">
465     Split dropright
466   </button>
467   <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
468     <span class="sr-only">Toggle Dropright</span>
469   </button>
470   <div class="dropdown-menu">
471     <!-- Dropdown menu links -->
472   </div>
473 </div>
474 {% endhighlight %}
475
476 ### Dropleft
477
478 Trigger dropdown menus at the left of the elements by adding `.dropleft` to the parent element.
479
480 <div class="bd-example">
481   <div class="btn-group dropleft">
482     <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
483       Dropleft
484     </button>
485     <div class="dropdown-menu">
486       <a class="dropdown-item" href="#">Action</a>
487       <a class="dropdown-item" href="#">Another action</a>
488       <a class="dropdown-item" href="#">Something else here</a>
489       <div class="dropdown-divider"></div>
490       <a class="dropdown-item" href="#">Separated link</a>
491     </div>
492   </div>
493
494   <div class="btn-group">
495     <div class="btn-group dropleft" role="group">
496       <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
497         <span class="sr-only">Toggle Dropleft</span>
498       </button>
499       <div class="dropdown-menu">
500         <a class="dropdown-item" href="#">Action</a>
501         <a class="dropdown-item" href="#">Another action</a>
502         <a class="dropdown-item" href="#">Something else here</a>
503         <div class="dropdown-divider"></div>
504         <a class="dropdown-item" href="#">Separated link</a>
505       </div>
506     </div>
507     <button type="button" class="btn btn-secondary">
508       Split dropleft
509     </button>
510   </div>
511 </div>
512
513 {% highlight html %}
514 <!-- Default dropleft button -->
515 <div class="btn-group dropleft">
516   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
517     Dropleft
518   </button>
519   <div class="dropdown-menu">
520     <!-- Dropdown menu links -->
521   </div>
522 </div>
523
524 <!-- Split dropleft button -->
525 <div class="btn-group">
526   <div class="btn-group dropleft" role="group">
527     <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
528       <span class="sr-only">Toggle Dropleft</span>
529     </button>
530     <div class="dropdown-menu">
531       <!-- Dropdown menu links -->
532     </div>
533   </div>
534   <button type="button" class="btn btn-secondary">
535     Split dropleft
536   </button>
537 </div>
538 {% endhighlight %}
539
540 ## Menu items
541
542 Historically 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.
543
544 {% capture example %}
545 <div class="dropdown">
546   <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
547     Dropdown
548   </button>
549   <div class="dropdown-menu" aria-labelledby="dropdownMenu2">
550     <button class="dropdown-item" type="button">Action</button>
551     <button class="dropdown-item" type="button">Another action</button>
552     <button class="dropdown-item" type="button">Something else here</button>
553   </div>
554 </div>
555 {% endcapture %}
556 {% include example.html content=example %}
557
558 You can also create non-interactive dropdown items with `.dropdown-item-text`. Feel free to style further with custom CSS or text utilities.
559
560 {% capture example %}
561 <div class="dropdown-menu">
562   <span class="dropdown-item-text">Dropdown item text</span>
563   <a class="dropdown-item" href="#">Action</a>
564   <a class="dropdown-item" href="#">Another action</a>
565   <a class="dropdown-item" href="#">Something else here</a>
566 </div>
567 {% endcapture %}
568 {% include example.html content=example %}
569
570 ### Active
571
572 Add `.active` to items in the dropdown to **style them as active**.
573
574 {% capture example %}
575 <div class="dropdown-menu">
576   <a class="dropdown-item" href="#">Regular link</a>
577   <a class="dropdown-item active" href="#">Active link</a>
578   <a class="dropdown-item" href="#">Another link</a>
579 </div>
580 {% endcapture %}
581 {% include example.html content=example %}
582
583 ### Disabled
584
585 Add `.disabled` to items in the dropdown to **style them as disabled**.
586
587 {% capture example %}
588 <div class="dropdown-menu">
589   <a class="dropdown-item" href="#">Regular link</a>
590   <a class="dropdown-item disabled" href="#" tabindex="-1" aria-disabled="true">Disabled link</a>
591   <a class="dropdown-item" href="#">Another link</a>
592 </div>
593 {% endcapture %}
594 {% include example.html content=example %}
595
596 ## Menu alignment
597
598 By 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.
599
600 {% capture callout %}
601 **Heads up!** Dropdowns are positioned thanks to Popper.js (except when they are contained in a navbar).
602 {% endcapture %}
603 {% include callout.html content=callout type="info" %}
604
605 {% capture example %}
606 <div class="btn-group">
607   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
608     Right-aligned menu
609   </button>
610   <div class="dropdown-menu dropdown-menu-right">
611     <button class="dropdown-item" type="button">Action</button>
612     <button class="dropdown-item" type="button">Another action</button>
613     <button class="dropdown-item" type="button">Something else here</button>
614   </div>
615 </div>
616 {% endcapture %}
617 {% include example.html content=example %}
618
619 ### Responsive alignment
620
621 If you want to use responsive alignment, disable dynamic positioning by adding the `data-display="static"` attribute and use the responsive variation classes.
622
623 To align **right** the dropdown menu with the given breakpoint or larger, add `.dropdown-menu{-sm|-md|-lg|-xl}-right`.
624
625 {% capture example %}
626 <div class="btn-group">
627   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
628     Left-aligned but right aligned when large screen
629   </button>
630   <div class="dropdown-menu dropdown-menu-lg-right">
631     <button class="dropdown-item" type="button">Action</button>
632     <button class="dropdown-item" type="button">Another action</button>
633     <button class="dropdown-item" type="button">Something else here</button>
634   </div>
635 </div>
636 {% endcapture %}
637 {% include example.html content=example %}
638
639 To align **left** the dropdown menu with the given breakpoint or larger, add `.dropdown-menu-right` and `.dropdown-menu{-sm|-md|-lg|-xl}-left`.
640
641 {% capture example %}
642 <div class="btn-group">
643   <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-haspopup="true" aria-expanded="false">
644     Right-aligned but left aligned when large screen
645   </button>
646   <div class="dropdown-menu dropdown-menu-right dropdown-menu-lg-left">
647     <button class="dropdown-item" type="button">Action</button>
648     <button class="dropdown-item" type="button">Another action</button>
649     <button class="dropdown-item" type="button">Something else here</button>
650   </div>
651 </div>
652 {% endcapture %}
653 {% include example.html content=example %}
654
655 Note that you don't need to add a `data-display="static"` attribute to dropdown buttons in navbars, since Popper.js isn't used in navbars.
656
657 ## Menu content
658
659 ### Headers
660
661 Add a header to label sections of actions in any dropdown menu.
662
663 {% capture example %}
664 <div class="dropdown-menu">
665   <h6 class="dropdown-header">Dropdown header</h6>
666   <a class="dropdown-item" href="#">Action</a>
667   <a class="dropdown-item" href="#">Another action</a>
668 </div>
669 {% endcapture %}
670 {% include example.html content=example %}
671
672 ### Dividers
673
674 Separate groups of related menu items with a divider.
675
676 {% capture example %}
677 <div class="dropdown-menu">
678   <a class="dropdown-item" href="#">Action</a>
679   <a class="dropdown-item" href="#">Another action</a>
680   <a class="dropdown-item" href="#">Something else here</a>
681   <div class="dropdown-divider"></div>
682   <a class="dropdown-item" href="#">Separated link</a>
683 </div>
684 {% endcapture %}
685 {% include example.html content=example %}
686
687 ### Text
688
689 Place any freeform text within a dropdown menu with text and use [spacing utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/). Note that you'll likely need additional sizing styles to constrain the menu width.
690
691 {% capture example %}
692 <div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
693   <p>
694     Some example text that's free-flowing within the dropdown menu.
695   </p>
696   <p class="mb-0">
697     And this is more example text.
698   </p>
699 </div>
700 {% endcapture %}
701 {% include example.html content=example %}
702
703 ### Forms
704
705 Put a form within a dropdown menu, or make it into a dropdown menu, and use [margin or padding utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/) to give it the negative space you require.
706
707 {% capture example %}
708 <div class="dropdown-menu">
709   <form class="px-4 py-3">
710     <div class="form-group">
711       <label for="exampleDropdownFormEmail1">Email address</label>
712       <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
713     </div>
714     <div class="form-group">
715       <label for="exampleDropdownFormPassword1">Password</label>
716       <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
717     </div>
718     <div class="form-group">
719       <div class="form-check">
720         <input type="checkbox" class="form-check-input" id="dropdownCheck">
721         <label class="form-check-label" for="dropdownCheck">
722           Remember me
723         </label>
724       </div>
725     </div>
726     <button type="submit" class="btn btn-primary">Sign in</button>
727   </form>
728   <div class="dropdown-divider"></div>
729   <a class="dropdown-item" href="#">New around here? Sign up</a>
730   <a class="dropdown-item" href="#">Forgot password?</a>
731 </div>
732 {% endcapture %}
733 {% include example.html content=example %}
734
735 {% capture example %}
736 <form class="dropdown-menu p-4">
737   <div class="form-group">
738     <label for="exampleDropdownFormEmail2">Email address</label>
739     <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@example.com">
740   </div>
741   <div class="form-group">
742     <label for="exampleDropdownFormPassword2">Password</label>
743     <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
744   </div>
745   <div class="form-group">
746     <div class="form-check">
747       <input type="checkbox" class="form-check-input" id="dropdownCheck2">
748       <label class="form-check-label" for="dropdownCheck2">
749         Remember me
750       </label>
751     </div>
752   </div>
753   <button type="submit" class="btn btn-primary">Sign in</button>
754 </form>
755 {% endcapture %}
756 {% include example.html content=example %}
757
758 ## Dropdown options
759
760 Use `data-offset` or `data-reference` to change the location of the dropdown.
761
762 {% capture example %}
763 <div class="d-flex">
764   <div class="dropdown mr-1">
765     <button type="button" class="btn btn-secondary dropdown-toggle" id="dropdownMenuOffset" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-offset="10,20">
766       Offset
767     </button>
768     <div class="dropdown-menu" aria-labelledby="dropdownMenuOffset">
769       <a class="dropdown-item" href="#">Action</a>
770       <a class="dropdown-item" href="#">Another action</a>
771       <a class="dropdown-item" href="#">Something else here</a>
772     </div>
773   </div>
774   <div class="btn-group">
775     <button type="button" class="btn btn-secondary">Reference</button>
776     <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" id="dropdownMenuReference" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" data-reference="parent">
777       <span class="sr-only">Toggle Dropdown</span>
778     </button>
779     <div class="dropdown-menu" aria-labelledby="dropdownMenuReference">
780       <a class="dropdown-item" href="#">Action</a>
781       <a class="dropdown-item" href="#">Another action</a>
782       <a class="dropdown-item" href="#">Something else here</a>
783       <div class="dropdown-divider"></div>
784       <a class="dropdown-item" href="#">Separated link</a>
785     </div>
786   </div>
787 </div>
788 {% endcapture %}
789 {% include example.html content=example %}
790
791 ## Usage
792
793 Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the `.show` class on the parent list item. 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.
794
795 {% capture callout %}
796 On touch-enabled devices, opening a dropdown adds empty (`$.noop`) `mouseover` handlers to the immediate children of the `<body>` element. This admittedly ugly hack is necessary to work around a [quirk in iOS' event delegation](https://www.quirksmode.org/blog/archives/2014/02/mouse_event_bub.html), which would otherwise prevent a tap anywhere outside of the dropdown from triggering the code that closes the dropdown. Once the dropdown is closed, these additional empty `mouseover` handlers are removed.
797 {% endcapture %}
798 {% include callout.html content=callout type="info" %}
799
800 ### Via data attributes
801
802 Add `data-toggle="dropdown"` to a link or button to toggle a dropdown.
803
804 {% highlight html %}
805 <div class="dropdown">
806   <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
807     Dropdown trigger
808   </button>
809   <div class="dropdown-menu" aria-labelledby="dLabel">
810     ...
811   </div>
812 </div>
813 {% endhighlight %}
814
815 ### Via JavaScript
816
817 Call the dropdowns via JavaScript:
818
819 {% highlight js %}
820 $('.dropdown-toggle').dropdown()
821 {% endhighlight %}
822
823 {% capture callout %}
824 ##### `data-toggle="dropdown"` still required
825
826 Regardless 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.
827 {% endcapture %}
828 {% include callout.html content=callout type="info" %}
829
830 ### Options
831
832 Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-offset=""`.
833
834 <table class="table table-bordered table-striped">
835   <thead>
836     <tr>
837       <th style="width: 100px;">Name</th>
838       <th style="width: 100px;">Type</th>
839       <th style="width: 50px;">Default</th>
840       <th>Description</th>
841     </tr>
842   </thead>
843   <tbody>
844     <tr>
845       <td>offset</td>
846       <td>number | string | function</td>
847       <td>0</td>
848       <td>Offset of the dropdown relative to its target. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..offset.offset">offset docs</a>.</td>
849     </tr>
850     <tr>
851       <td>flip</td>
852       <td>boolean</td>
853       <td>true</td>
854       <td>Allow Dropdown to flip in case of an overlapping on the reference element. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..flip.enabled">flip docs</a>.</td>
855     </tr>
856     <tr>
857       <td>boundary</td>
858       <td>string | element</td>
859       <td>'scrollParent'</td>
860       <td>Overflow constraint boundary of the dropdown menu. Accepts the values of <code>'viewport'</code>, <code>'window'</code>, <code>'scrollParent'</code>, or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement">preventOverflow docs</a>.</td>
861     </tr>
862     <tr>
863       <td>reference</td>
864       <td>string | element</td>
865       <td>'toggle'</td>
866       <td>Reference element of the dropdown menu. Accepts the values of <code>'toggle'</code>, <code>'parent'</code>, or an HTMLElement reference. For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#referenceObject">referenceObject docs</a>.</td>
867     </tr>
868     <tr>
869       <td>display</td>
870       <td>string</td>
871       <td>'dynamic'</td>
872       <td>By default, we use Popper.js for dynamic positioning. Disable this with <code>static</code>.</td>
873     </tr>
874   </tbody>
875 </table>
876
877 Note when `boundary` is set to any value other than `'scrollParent'`, the style `position: static` is applied to the `.dropdown` container.
878
879 ### Methods
880
881 | Method | Description |
882 | --- | --- |
883 | `$().dropdown('toggle')` | Toggles the dropdown menu of a given navbar or tabbed navigation. |
884 | `$().dropdown('show')` | Shows the dropdown menu of a given navbar or tabbed navigation. |
885 | `$().dropdown('hide')` | Hides the dropdown menu of a given navbar or tabbed navigation. |
886 | `$().dropdown('update')` | Updates the position of an element's dropdown. |
887 | `$().dropdown('dispose')` | Destroys an element's dropdown. |
888
889 ### Events
890
891 All dropdown events are fired at the `.dropdown-menu`'s parent element and have a `relatedTarget` property, whose value is the toggling anchor element.
892 `hide.bs.dropdown` and `hidden.bs.dropdown` events have a `clickEvent` property (only when the original event type is `click`) that contains an Event Object for the click event.
893
894 | Event | Description |
895 | --- | --- |
896 | `show.bs.dropdown` | This event fires immediately when the show instance method is called. |
897 | `shown.bs.dropdown` | This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete). |
898 | `hide.bs.dropdown` | This event is fired immediately when the hide instance method has been called. |
899 | `hidden.bs.dropdown`| This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete). |
900
901 {% highlight js %}
902 $('#myDropdown').on('show.bs.dropdown', function () {
903   // do something…
904 })
905 {% endhighlight %}