diff options
Diffstat (limited to 'docs/components/dropdowns.md')
| -rw-r--r-- | docs/components/dropdowns.md | 389 |
1 files changed, 381 insertions, 8 deletions
diff --git a/docs/components/dropdowns.md b/docs/components/dropdowns.md index 09d518a60..affaadc6e 100644 --- a/docs/components/dropdowns.md +++ b/docs/components/dropdowns.md @@ -11,16 +11,20 @@ Dropdowns are toggleable, contextual overlays for displaying lists of links and * Will be replaced with the ToC, excluding the "Contents" header {:toc} -## Example +## Examples -Wrap the dropdown's trigger and the dropdown menu within `.dropdown`, or another element that declares `position: relative;`. Then, add the menu's HTML. +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 open"> - <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu1" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - 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="dropdownMenu1"> + <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> @@ -28,9 +32,378 @@ Wrap the dropdown's trigger and the dropdown menu within `.dropdown`, or another </div> {% endexample %} -### Button elements +And with `<a>` elements: + +{% example html %} +<div class="dropdown open"> + <a class="btn btn-secondary dropdown-toggle" href="http://example.com" id="dropdownMenuLink" data-target="#" 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-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Default</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-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-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-secondary">Default</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-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-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"> + <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"> + <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-toolbar" role="toolbar"> + <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" 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> +</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 -You can optionally use `<button>` elements in your dropdowns instead of `<a>`s. +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 open"> @@ -45,7 +418,7 @@ You can optionally use `<button>` elements in your dropdowns instead of `<a>`s. </div> {% endexample %} -## Alignment +## 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. |