5.9 KiB
| layout | title | group |
|---|---|---|
| docs | Dropdowns | 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}
Example
Wrap the dropdown's trigger and the dropdown menu within .dropdown, or another element that declares position: relative;. Then, add the menu's HTML.
{% example html %}
{% endexample %}Button elements
You can optionally use <button> elements in your dropdowns instead of <a>s.
{% example html %}
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 %}
{% highlight 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 .open 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 %}
To keep URLs intact with link buttons, use the data-target attribute instead of href="#".
{% 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 %}