0
0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-10 22:24:19 +01:00
Bootstrap/docs/components/dropdowns.md

184 lines
5.1 KiB
Markdown
Raw Normal View History

2014-07-12 07:34:47 +02:00
---
layout: page
title: Dropdowns
group: components
2014-07-12 07:34:47 +02:00
---
2015-08-11 01:16:39 +02:00
Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They're made interactive with the included Bootstrap dropdown JavaScript plugin.
2014-07-12 07:34:47 +02:00
2015-05-29 10:58:52 +02:00
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
## Example
2014-07-12 07:34:47 +02:00
Wrap the dropdown's trigger and the dropdown menu within `.dropdown`, or another element that declares `position: relative;`. Then, add the menu's HTML.
2014-07-12 07:34:47 +02:00
{% example html %}
<div class="dropdown open">
2015-06-19 08:56:43 +02:00
<button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu1" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
2014-07-12 07:34:47 +02:00
Dropdown
</button>
2015-06-19 08:56:43 +02:00
<ul class="dropdown-menu" aria-labelledby="dropdownMenu1">
<li>
<a href="#">Action</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li>
<a href="#">Another action</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li>
<a href="#">Something else here</a>
2014-07-12 07:34:47 +02:00
</li>
</ul>
</div>
{% endexample %}
## Alignment
2014-07-12 07:34:47 +02: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.
{% callout info %}
**Heads up!** Dropdowns are positioned only with CSS and may need some additional styles for exact alignment.
{% endcallout %}
2014-07-12 07:34:47 +02:00
{% highlight html %}
2015-06-19 08:56:43 +02:00
<ul class="dropdown-menu dropdown-menu-right" aria-labelledby="dLabel">
2014-07-12 07:34:47 +02:00
...
</ul>
{% endhighlight %}
## Menu headers
2014-07-12 07:34:47 +02:00
Add a header to label sections of actions in any dropdown menu.
{% example html %}
2015-06-19 08:56:43 +02:00
<ul class="dropdown-menu">
<li class="dropdown-header">Dropdown header</li>
<li>
<a href="#">Action</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li>
<a href="#">Another action</a>
2014-07-12 07:34:47 +02:00
</li>
</ul>
{% endexample %}
## Menu dividers
2014-07-12 07:34:47 +02:00
Separate groups of related menu items with a divider.
{% example html %}
2015-06-19 08:56:43 +02:00
<ul class="dropdown-menu">
<li>
<a href="#">Action</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li>
<a href="#">Another action</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li>
<a href="#">Something else here</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li class="dropdown-divider"></li>
<li>
<a href="#">Separated link</a>
2014-07-12 07:34:47 +02:00
</li>
</ul>
{% endexample %}
## Disabled menu items
2014-07-12 07:34:47 +02:00
Add `.disabled` to a `<li>` in the dropdown to disable the link.
{% example html %}
2015-06-19 08:56:43 +02:00
<ul class="dropdown-menu">
<li>
<a href="#">Regular link</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li class="disabled">
<a href="#">Disabled link</a>
2014-07-12 07:34:47 +02:00
</li>
2015-06-19 08:56:43 +02:00
<li>
<a href="#">Another link</a>
2014-07-12 07:34:47 +02:00
</li>
</ul>
{% 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 %}
<div class="dropdown">
2015-06-19 08:56:43 +02:00
<button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Dropdown trigger
</button>
2015-06-19 08:56:43 +02:00
<ul class="dropdown-menu" aria-labelledby="dLabel">
...
</ul>
</div>
{% endhighlight %}
To keep URLs intact with link buttons, use the `data-target` attribute instead of `href="#"`.
{% highlight html %}
<div class="dropdown">
2015-06-19 08:56:43 +02:00
<a id="dLabel" data-target="#" href="http://example.com" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Dropdown trigger
</a>
2015-06-19 08:56:43 +02:00
<ul class="dropdown-menu" aria-labelledby="dLabel">
...
</ul>
</div>
{% endhighlight %}
### 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
2015-08-11 01:16:39 +02:00
| 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.
2015-08-11 01:16:39 +02: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). |
{% highlight js %}
$('#myDropdown').on('show.bs.dropdown', function () {
// do something…
})
{% endhighlight %}