2014-07-12 05:34:47 +00:00
---
2015-08-15 05:45:55 +00:00
layout: docs
2014-07-12 05:34:47 +00:00
title: Dropdowns
2016-10-03 01:19:47 +00:00
description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin.
2015-08-06 00:47:45 +00:00
group: components
2014-07-12 05:34:47 +00:00
---
2015-08-24 23:32:32 +00:00
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/ )
2014-07-12 05:34:47 +00:00
2015-05-29 08:58:52 +00:00
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
2016-05-11 21:13:16 +00:00
## Examples
2014-07-12 05:34:47 +00:00
2016-05-11 21:13:16 +00:00
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.
### Single button dropdowns
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:
2014-07-12 05:34:47 +00:00
{% example html %}
2017-01-04 03:24:24 +00:00
< div class = "dropdown" >
2016-05-11 21:13:16 +00:00
< button class = "btn btn-secondary dropdown-toggle" type = "button" id = "dropdownMenuButton" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Dropdown button
2014-07-12 05:34:47 +00:00
< / button >
2016-05-11 21:13:16 +00:00
< div class = "dropdown-menu" aria-labelledby = "dropdownMenuButton" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< / div >
< / div >
{% endexample %}
And with `<a>` elements:
{% example html %}
2016-10-27 22:13:17 +00:00
< div class = "dropdown show" >
2016-10-03 16:55:59 +00:00
< a class = "btn btn-secondary dropdown-toggle" href = "https://example.com" id = "dropdownMenuLink" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
2016-05-11 21:13:16 +00:00
Dropdown link
< / a >
< div class = "dropdown-menu" aria-labelledby = "dropdownMenuLink" >
2015-08-17 18:19:14 +00:00
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< / div >
2014-07-12 05:34:47 +00:00
< / div >
{% endexample %}
2016-05-11 21:13:16 +00:00
The best part is you can do this with any button variant, too:
< div class = "bd-example" >
< div class = "btn-group" >
2016-10-27 08:12:14 +00:00
< button type = "button" class = "btn btn-primary dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" > Primary< / button >
2016-05-11 21:13:16 +00:00
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
2016-10-27 08:12:14 +00:00
< button type = "button" class = "btn btn-secondary dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" > Secondary< / button >
2016-05-11 21:13:16 +00:00
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-success dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" > Success< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-info dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" > Info< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-warning dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" > Warning< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-danger dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" > Danger< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< / div >
{% highlight html %}
<!-- Example single danger button -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-danger dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Action
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div >
{% endhighlight %}
### Split button dropdowns
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.
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.
< div class = "bd-example" >
< div class = "btn-group" >
2016-10-27 08:12:14 +00:00
< button type = "button" class = "btn btn-primary" > Primary< / button >
< button type = "button" class = "btn btn-primary dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
2016-05-11 21:13:16 +00:00
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
2016-10-27 08:12:14 +00:00
< button type = "button" class = "btn btn-secondary" > Secondary< / button >
< button type = "button" class = "btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
2016-05-11 21:13:16 +00:00
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-success" > Success< / button >
< button type = "button" class = "btn btn-success dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-info" > Info< / button >
< button type = "button" class = "btn btn-info dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-warning" > Warning< / button >
< button type = "button" class = "btn btn-warning dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-danger" > Danger< / button >
< button type = "button" class = "btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< / div >
{% highlight html %}
<!-- Example split danger button -->
< div class = "btn-group" >
< button type = "button" class = "btn btn-danger" > Action< / button >
< button type = "button" class = "btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div >
{% endhighlight %}
## Sizing
Button dropdowns work with buttons of all sizes, including default and split dropdown buttons.
< div class = "bd-example" >
< div class = "btn-toolbar" role = "toolbar" >
< div class = "btn-group" >
< button class = "btn btn-secondary btn-lg dropdown-toggle" type = "button" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Large button
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
2017-01-04 03:24:24 +00:00
< div class = "btn-group ml-2" >
2016-05-11 21:13:16 +00:00
< button type = "button" class = "btn btn-lg btn-secondary" > Large split button< / button >
< button type = "button" class = "btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< / div > <!-- /btn - toolbar -->
< div class = "btn-toolbar" role = "toolbar" >
< div class = "btn-group" >
< button class = "btn btn-secondary btn-sm dropdown-toggle" type = "button" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Small button
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
2017-01-04 03:24:24 +00:00
< div class = "btn-group ml-2" >
2016-05-11 21:13:16 +00:00
< button type = "button" class = "btn btn-sm btn-secondary" > Small split button< / button >
< button type = "button" class = "btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
< / div > <!-- /btn - group -->
< / div > <!-- /btn - toolbar -->
< / div > <!-- /example -->
{% highlight html %}
<!-- Large button groups (default and split) -->
< div class = "btn-group" >
< button class = "btn btn-secondary btn-lg dropdown-toggle" type = "button" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Large button
< / button >
< div class = "dropdown-menu" >
...
< / div >
< / div >
< div class = "btn-group" >
< button class = "btn btn-secondary btn-lg dropdown-toggle" type = "button" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Large button
< / button >
< button type = "button" class = "btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
...
< / div >
< / div >
<!-- Small button groups (default and split) -->
< div class = "btn-group" >
< button class = "btn btn-secondary btn-sm dropdown-toggle" type = "button" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Small button
< / button >
< div class = "dropdown-menu" >
...
< / div >
< / div >
< div class = "btn-group" >
< button class = "btn btn-secondary btn-sm dropdown-toggle" type = "button" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Small button
< / button >
< button type = "button" class = "btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
...
< / div >
< / div >
{% endhighlight %}
## Dropup variation
Trigger dropdown menus above elements by adding `.dropup` to the parent element.
< div class = "bd-example" >
2017-01-04 03:24:24 +00:00
< div class = "btn-group dropup" >
< button type = "button" class = "btn btn-secondary dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
Dropup
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
2016-05-11 21:13:16 +00:00
< / div >
2017-01-04 03:24:24 +00:00
< / div >
2016-05-11 21:13:16 +00:00
2017-01-04 03:24:24 +00:00
< div class = "btn-group dropup" >
< button type = "button" class = "btn btn-secondary" >
Split dropup
< / button >
< button type = "button" class = "btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
2016-05-11 21:13:16 +00:00
< / div >
< / div >
< / div >
{% highlight html %}
<!-- Default dropup button -->
< div class = "btn-group dropup" >
< button type = "button" class = "btn btn-secondary" > Dropup< / button >
< button type = "button" class = "btn btn-secondary dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
<!-- Dropdown menu links -->
< / div >
< / div >
<!-- Split dropup button -->
< div class = "btn-group dropup" >
< button type = "button" class = "btn btn-secondary" >
Split dropup
< / button >
< button type = "button" class = "btn btn-secondary dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
< span class = "sr-only" > Toggle Dropdown< / span >
< / button >
< div class = "dropdown-menu" >
<!-- Dropdown menu links -->
< / div >
< / div >
{% endhighlight %}
## Menu items
2015-08-18 01:18:37 +00:00
2016-05-11 21:13:16 +00:00
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.
2015-08-18 01:18:37 +00:00
{% example html %}
2017-01-04 03:24:24 +00:00
< div class = "dropdown" >
2015-08-25 12:37:08 +00:00
< button class = "btn btn-secondary dropdown-toggle" type = "button" id = "dropdownMenu2" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
2015-08-18 01:18:37 +00:00
Dropdown
< / button >
2015-08-25 12:37:08 +00:00
< div class = "dropdown-menu" aria-labelledby = "dropdownMenu2" >
2015-08-18 01:18:37 +00:00
< button class = "dropdown-item" type = "button" > Action< / button >
< button class = "dropdown-item" type = "button" > Another action< / button >
< button class = "dropdown-item" type = "button" > Something else here< / button >
< / div >
< / div >
{% endexample %}
2016-05-11 21:13:16 +00:00
## Menu alignment
2014-07-12 05:34:47 +00:00
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.
2015-08-10 23:31:28 +00:00
{% callout info %}
**Heads up!** Dropdowns are positioned only with CSS and may need some additional styles for exact alignment.
2015-04-16 23:56:40 +00:00
{% endcallout %}
2014-07-12 05:34:47 +00:00
2016-01-11 00:02:33 +00:00
{% example html %}
< div class = "btn-group" >
< button type = "button" class = "btn btn-secondary dropdown-toggle" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
This dropdown's menu is right-aligned
< / button >
< div class = "dropdown-menu dropdown-menu-right" >
< button class = "dropdown-item" type = "button" > Action< / button >
< button class = "dropdown-item" type = "button" > Another action< / button >
< button class = "dropdown-item" type = "button" > Something else here< / button >
< / div >
2015-08-17 18:19:14 +00:00
< / div >
2016-01-11 00:02:33 +00:00
{% endexample %}
2014-07-12 05:34:47 +00:00
2015-03-31 01:23:35 +00:00
## Menu headers
2014-07-12 05:34:47 +00:00
Add a header to label sections of actions in any dropdown menu.
{% example html %}
2015-08-17 18:19:14 +00:00
< div class = "dropdown-menu" >
< h6 class = "dropdown-header" > Dropdown header< / h6 >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< / div >
2014-07-12 05:34:47 +00:00
{% endexample %}
2015-03-31 01:23:35 +00:00
## Menu dividers
2014-07-12 05:34:47 +00:00
Separate groups of related menu items with a divider.
{% example html %}
2015-08-17 18:19:14 +00:00
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Action< / a >
< a class = "dropdown-item" href = "#" > Another action< / a >
< a class = "dropdown-item" href = "#" > Something else here< / a >
< div class = "dropdown-divider" > < / div >
< a class = "dropdown-item" href = "#" > Separated link< / a >
< / div >
2014-07-12 05:34:47 +00:00
{% endexample %}
2015-03-31 01:23:35 +00:00
## Disabled menu items
2014-07-12 05:34:47 +00:00
2015-08-17 18:19:14 +00:00
Add `.disabled` to items in the dropdown to **style them as disabled** .
2014-07-12 05:34:47 +00:00
{% example html %}
2015-08-17 18:19:14 +00:00
< div class = "dropdown-menu" >
< a class = "dropdown-item" href = "#" > Regular link< / a >
< a class = "dropdown-item disabled" href = "#" > Disabled link< / a >
< a class = "dropdown-item" href = "#" > Another link< / a >
< / div >
2014-07-12 05:34:47 +00:00
{% endexample %}
2015-03-31 01:23:35 +00:00
## Usage
2016-10-27 22:13:17 +00:00
Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the `.show` class on the parent list item.
2015-03-31 01:23:35 +00:00
Replace dropdown backdrop hack with cleaner JS-only hack
* Replace backdrop with simple noop mouse listener
As discussed in https://github.com/twbs/bootstrap/pull/22422 the current
approach of injecting a backdrop (to work around iOS' broken event
delegation for the `click` event) has annoying consequences on
touch-enabled laptop/desktop devices.
Instead of a backdrop `<div>`, here we simply add extra empty/noop
mouse listeners to the immediate children of `<body>` (and remove
them when the dropdown is closed) in order to force iOS to properly
bubble a `click` resulting from a tap (essentially, method 2 from
https://www.quirksmode.org/blog/archives/2014/02/mouse_event_bub.html)
This is sufficient (except in rare cases where the user does manage to tap
on the body itself, rather than any child elements of body - which is not
very likely in an iOS phone/tablet scenario for most layouts) to get iOS to
get a grip and do the correct event bubbling/delegation, meaning the regular
"click" event will bubble back to the `<body>` when tapping outside of the dropdown,
and the dropdown will close properly (just like it already does, even without
this fix, in non-iOS touchscreen devices/browsers, like Chrome/Android and
Windows on a touch laptop).
This approach, though a bit hacky, has no impact on the DOM structure, and
has no unforeseen side effects on touch-enabled laptops/desktops. And crucially,
it works just fine in iOS.
* Remove dropdown backdrop styles
* Update doc for dropdowns and touch-enabled devices
2017-04-14 08:19:00 +00:00
{% callout info %}
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.
{% endcallout %}
2015-03-31 01:23:35 +00:00
Note: 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.
### Via data attributes
Add `data-toggle="dropdown"` to a link or button to toggle a dropdown.
{% highlight html %}
< div class = "dropdown" >
2015-06-19 06:56:43 +00:00
< button id = "dLabel" type = "button" data-toggle = "dropdown" aria-haspopup = "true" aria-expanded = "false" >
2015-03-31 01:23:35 +00:00
Dropdown trigger
< / button >
2015-08-17 18:19:14 +00:00
< div class = "dropdown-menu" aria-labelledby = "dLabel" >
2015-03-31 01:23:35 +00:00
...
2015-08-17 18:19:14 +00:00
< / div >
2015-03-31 01:23:35 +00:00
< / div >
{% endhighlight %}
### Via JavaScript
Call the dropdowns via JavaScript:
{% highlight js %}
$('.dropdown-toggle').dropdown()
{% endhighlight %}
2015-04-16 23:56:40 +00:00
{% callout info %}
2017-01-04 03:24:24 +00:00
##### `data-toggle="dropdown"` still required
2015-04-16 23:56:40 +00:00
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.
{% endcallout %}
2015-03-31 01:23:35 +00:00
### Options
*None.*
### Methods
2015-08-10 23:16:39 +00:00
| Method | Description |
| --- | --- |
| `$().dropdown('toggle')` | Toggles the dropdown menu of a given navbar or tabbed navigation. |
2015-03-31 01:23:35 +00:00
### Events
All dropdown events are fired at the `.dropdown-menu` 's parent element and have a `relatedTarget` property, whose value is the toggling anchor element.
2015-08-10 23:16:39 +00:00
| Event | Description |
| --- | --- |
| `show.bs.dropdown` | This event fires immediately when the show instance method is called. |
| `shown.bs.dropdown` | This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete). |
| `hide.bs.dropdown` | This event is fired immediately when the hide instance method has been called. |
| `hidden.bs.dropdown` | This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete). |
2015-03-31 01:23:35 +00:00
{% highlight js %}
$('#myDropdown').on('show.bs.dropdown', function () {
// do something…
})
{% endhighlight %}
