diff options
Diffstat (limited to 'docs/components/dropdowns.md')
| -rw-r--r-- | docs/components/dropdowns.md | 541 |
1 files changed, 0 insertions, 541 deletions
diff --git a/docs/components/dropdowns.md b/docs/components/dropdowns.md deleted file mode 100644 index 3c68f9453..000000000 --- a/docs/components/dropdowns.md +++ /dev/null @@ -1,541 +0,0 @@ ---- -layout: docs -title: Dropdowns -description: Toggle contextual overlays for displaying lists of links and more with the Bootstrap dropdown plugin. -group: 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.](http://markdotto.com/2012/02/27/bootstrap-explained-dropdowns/) - -## 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 %} -<div class="dropdown"> - <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown button - </button> - <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 %} -<div class="dropdown show"> - <a class="btn btn-secondary dropdown-toggle" href="https://example.com" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown link - </a> - - <div class="dropdown-menu" aria-labelledby="dropdownMenuLink"> - <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 %} - -The best part is you can do this with any button variant, too: - -<div class="bd-example"> - <div class="btn-group"> - <button type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Primary</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-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Secondary</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 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"> - <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"> - <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-secondary">Secondary</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><!-- /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 --> - <div class="btn-group ml-2"> - <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 --> - <div class="btn-group ml-2"> - <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"> - <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> - </div> - </div> - - <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> -</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 - -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 %} -<div class="dropdown"> - <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown - </button> - <div class="dropdown-menu" aria-labelledby="dropdownMenu2"> - <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 %} - -## 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 %} -<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> -</div> -{% endexample %} - -## Menu headers - -Add a header to label sections of actions in any dropdown menu. - -{% example html %} -<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> -{% endexample %} - -## Menu dividers - -Separate groups of related menu items with a divider. - -{% example html %} -<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> -{% endexample %} - -## Disabled menu items - -Add `.disabled` to items in the dropdown to **style them as disabled**. - -{% example html %} -<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> -{% 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. - -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"> - <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Dropdown trigger - </button> - <div class="dropdown-menu" aria-labelledby="dLabel"> - ... - </div> -</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 - -| 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 %} |