22 KiB
| layout | title | description | group |
|---|---|---|---|
| docs | Dropdowns | Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin. | components |
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.
Contents
- Will be replaced with the ToC, excluding the "Contents" header {:toc}
Examples
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:
{% example html %}
And with <a> elements:
{% example html %}
{% endexample %}The best part is you can do this with any button variant, too:
{% highlight html %}
{% 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.
{% highlight html %}
Sizing
Button dropdowns work with buttons of all sizes, including default and split dropdown buttons.
{% highlight html %}
Dropup variation
Trigger dropdown menus above elements by adding .dropup to the parent element.
<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>
</div>
</div>
{% highlight html %}
Menu items
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.
{% example html %}
Menu alignment
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.
{% callout info %} Heads up! Dropdowns are positioned only with CSS and may need some additional styles for exact alignment. {% endcallout %}
{% example html %}
Menu headers
Add a header to label sections of actions in any dropdown menu.
{% example html %}
{% endexample %}Menu dividers
Separate groups of related menu items with a divider.
{% example html %}
{% endexample %}Disabled menu items
Add .disabled to items in the dropdown to style them as disabled.
{% example html %}
{% endexample %}Usage
Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the .active class on the parent list item.
On 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.
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 %}
Via JavaScript
Call the dropdowns via JavaScript:
{% highlight js %} $('.dropdown-toggle').dropdown() {% endhighlight %}
{% callout info %}
data-toggle="dropdown" still required
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 %}
Options
None.
Methods
| Method | Description |
|---|---|
$().dropdown('toggle') |
Toggles the dropdown menu of a given navbar or tabbed navigation. |
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.
| 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). |
{% highlight js %} $('#myDropdown').on('show.bs.dropdown', function () { // do something… }) {% endhighlight %}