6d64afe508
* 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
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.
{% 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 .show class on the parent list item.
{% 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, 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 %}
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 %}