diff --git a/docs/components/button-group.md b/docs/components/button-group.md
index a07677c07a654229b84bdd6101ec1d34b97c1a34..178245e942aa7e9387427189b195bab7592416c7 100644
--- a/docs/components/button-group.md
+++ b/docs/components/button-group.md
@@ -3,93 +3,83 @@ layout: page
title: Button group
---
-<div class="bs-docs-section">
- <h1 id="btn-groups" class="page-header">Button groups</h1>
+Group a series of buttons together on a single line with the button group. Add on optional JavaScript radio and checkbox style behavior with [our buttons plugin](../javascript/#buttons).
- <p class="lead">Group a series of buttons together on a single line with the button group. Add on optional JavaScript radio and checkbox style behavior with <a href="../javascript/#buttons">our buttons plugin</a>.</p>
+<div class="bs-callout bs-callout-warning">
+ <h4>Tooltips & popovers in button groups require special setting</h4>
+ <p>When using tooltips or popovers on elements within a <code>.btn-group</code>, you'll have to specify the option <code>container: 'body'</code> to avoid unwanted side effects (such as the element growing wider and/or losing its rounded corners when the tooltip or popover is triggered).</p>
+</div>
- <div class="bs-callout bs-callout-warning">
- <h4>Tooltips & popovers in button groups require special setting</h4>
- <p>When using tooltips or popovers on elements within a <code>.btn-group</code>, you'll have to specify the option <code>container: 'body'</code> to avoid unwanted side effects (such as the element growing wider and/or losing its rounded corners when the tooltip or popover is triggered).</p>
- </div>
+### Basic example
- <h3 id="btn-groups-single">Basic example</h3>
- <p>Wrap a series of buttons with <code>.btn</code> in <code>.btn-group</code>.</p>
- <div class="bs-example">
- <div class="btn-group" style="margin: 9px 0 5px;">
- <button type="button" class="btn btn-secondary">Left</button>
- <button type="button" class="btn btn-secondary">Middle</button>
- <button type="button" class="btn btn-secondary">Right</button>
- </div>
- </div>
-{% highlight html %}
+Wrap a series of buttons with `.btn` in `.btn-group`.
+
+{% example html %}
<div class="btn-group">
<button type="button" class="btn btn-secondary">Left</button>
<button type="button" class="btn btn-secondary">Middle</button>
<button type="button" class="btn btn-secondary">Right</button>
</div>
-{% endhighlight %}
+{% endexample %}
- <h3 id="btn-groups-toolbar">Button toolbar</h3>
- <p>Combine sets of <code><div class="btn-group"></code> into a <code><div class="btn-toolbar"></code> for more complex components.</p>
- <div class="bs-example">
- <div class="btn-toolbar" role="toolbar" style="margin: 0;">
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">1</button>
- <button type="button" class="btn btn-secondary">2</button>
- <button type="button" class="btn btn-secondary">3</button>
- <button type="button" class="btn btn-secondary">4</button>
- </div>
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">5</button>
- <button type="button" class="btn btn-secondary">6</button>
- <button type="button" class="btn btn-secondary">7</button>
- </div>
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">8</button>
- </div>
- </div>
- </div>
-{% highlight html %}
+### Button toolbar
+
+Combine sets of button groups into button toolbars for more complex components.
+
+{% example html %}
<div class="btn-toolbar" role="toolbar">
- <div class="btn-group">...</div>
- <div class="btn-group">...</div>
- <div class="btn-group">...</div>
+ <div class="btn-group">
+ <button type="button" class="btn btn-secondary">1</button>
+ <button type="button" class="btn btn-secondary">2</button>
+ <button type="button" class="btn btn-secondary">3</button>
+ <button type="button" class="btn btn-secondary">4</button>
+ </div>
+ <div class="btn-group">
+ <button type="button" class="btn btn-secondary">5</button>
+ <button type="button" class="btn btn-secondary">6</button>
+ <button type="button" class="btn btn-secondary">7</button>
+ </div>
+ <div class="btn-group">
+ <button type="button" class="btn btn-secondary">8</button>
+ </div>
</div>
-{% endhighlight %}
+{% endexample %}
+
+### Sizing
+
+Instead of applying button sizing classes to every button in a group, just add `.btn-group-*` to the `.btn-group`.
- <h3 id="btn-groups-sizing">Sizing</h3>
- <p>Instead of applying button sizing classes to every button in a group, just add <code>.btn-group-*</code> to the <code>.btn-group</code>.</p>
- <div class="bs-example">
- <div class="btn-toolbar" role="toolbar">
- <div class="btn-group btn-group-lg">
- <button type="button" class="btn btn-secondary">Left</button>
- <button type="button" class="btn btn-secondary">Middle</button>
- <button type="button" class="btn btn-secondary">Right</button>
- </div>
+<div class="bs-example">
+ <div class="btn-toolbar" role="toolbar">
+ <div class="btn-group btn-group-lg">
+ <button type="button" class="btn btn-secondary">Left</button>
+ <button type="button" class="btn btn-secondary">Middle</button>
+ <button type="button" class="btn btn-secondary">Right</button>
</div>
- <div class="btn-toolbar" role="toolbar">
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">Left</button>
- <button type="button" class="btn btn-secondary">Middle</button>
- <button type="button" class="btn btn-secondary">Right</button>
- </div>
+ </div>
+ <div class="btn-toolbar" role="toolbar">
+ <div class="btn-group">
+ <button type="button" class="btn btn-secondary">Left</button>
+ <button type="button" class="btn btn-secondary">Middle</button>
+ <button type="button" class="btn btn-secondary">Right</button>
</div>
- <div class="btn-toolbar" role="toolbar">
- <div class="btn-group btn-group-sm">
- <button type="button" class="btn btn-secondary">Left</button>
- <button type="button" class="btn btn-secondary">Middle</button>
- <button type="button" class="btn btn-secondary">Right</button>
- </div>
+ </div>
+ <div class="btn-toolbar" role="toolbar">
+ <div class="btn-group btn-group-sm">
+ <button type="button" class="btn btn-secondary">Left</button>
+ <button type="button" class="btn btn-secondary">Middle</button>
+ <button type="button" class="btn btn-secondary">Right</button>
</div>
- <div class="btn-toolbar" role="toolbar">
- <div class="btn-group btn-group-xs">
- <button type="button" class="btn btn-secondary">Left</button>
- <button type="button" class="btn btn-secondary">Middle</button>
- <button type="button" class="btn btn-secondary">Right</button>
- </div>
+ </div>
+ <div class="btn-toolbar" role="toolbar">
+ <div class="btn-group btn-group-xs">
+ <button type="button" class="btn btn-secondary">Left</button>
+ <button type="button" class="btn btn-secondary">Middle</button>
+ <button type="button" class="btn btn-secondary">Right</button>
</div>
</div>
+</div>
+
{% highlight html %}
<div class="btn-group btn-group-lg">...</div>
<div class="btn-group">...</div>
@@ -97,153 +87,144 @@ title: Button group
<div class="btn-group btn-group-xs">...</div>
{% endhighlight %}
- <h3 id="btn-groups-nested">Nesting</h3>
- <p>Place a <code>.btn-group</code> within another <code>.btn-group</code> when you want dropdown menus mixed with a series of buttons.</p>
- <div class="bs-example">
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">1</button>
- <button type="button" class="btn btn-secondary">2</button>
+### Nesting
- <div class="btn-group">
- <button id="btnGroupDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
- Dropdown
- </button>
- <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupDrop1">
- <li><a href="#">Dropdown link</a></li>
- <li><a href="#">Dropdown link</a></li>
- </ul>
- </div>
- </div>
- </div>
-{% highlight html %}
+Place a `.btn-group` within another `.btn-group` when you want dropdown menus mixed with a series of buttons.
+
+{% example html %}
<div class="btn-group">
<button type="button" class="btn btn-secondary">1</button>
<button type="button" class="btn btn-secondary">2</button>
<div class="btn-group">
- <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
+ <button id="btnGroupDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
Dropdown
</button>
- <ul class="dropdown-menu" role="menu">
+ <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupDrop1">
<li><a href="#">Dropdown link</a></li>
<li><a href="#">Dropdown link</a></li>
</ul>
</div>
</div>
-{% endhighlight %}
+{% endexample %}
- <h3 id="btn-groups-vertical">Vertical variation</h3>
- <p>Make a set of buttons appear vertically stacked rather than horizontally. <strong class="text-danger">Split button dropdowns are not supported here.</strong></p>
- <div class="bs-example">
- <div class="btn-group-vertical">
- <button type="button" class="btn btn-secondary">Button</button>
- <button type="button" class="btn btn-secondary">Button</button>
- <div class="btn-group">
- <button id="btnGroupVerticalDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
- Dropdown
- </button>
- <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop1">
- <li><a href="#">Dropdown link</a></li>
- <li><a href="#">Dropdown link</a></li>
- </ul>
- </div>
- <button type="button" class="btn btn-secondary">Button</button>
- <button type="button" class="btn btn-secondary">Button</button>
- <div class="btn-group">
- <button id="btnGroupVerticalDrop2" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
- Dropdown
- </button>
- <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop2">
- <li><a href="#">Dropdown link</a></li>
- <li><a href="#">Dropdown link</a></li>
- </ul>
- </div>
- <div class="btn-group">
- <button id="btnGroupVerticalDrop3" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
- Dropdown
- </button>
- <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop3">
- <li><a href="#">Dropdown link</a></li>
- <li><a href="#">Dropdown link</a></li>
- </ul>
- </div>
- <div class="btn-group">
- <button id="btnGroupVerticalDrop4" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
- Dropdown
- </button>
- <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop4">
- <li><a href="#">Dropdown link</a></li>
- <li><a href="#">Dropdown link</a></li>
- </ul>
- </div>
+### Vertical variation
+
+Make a set of buttons appear vertically stacked rather than horizontally. **Split button dropdowns are not supported here.**
+
+<div class="bs-example">
+ <div class="btn-group-vertical">
+ <button type="button" class="btn btn-secondary">Button</button>
+ <button type="button" class="btn btn-secondary">Button</button>
+ <div class="btn-group">
+ <button id="btnGroupVerticalDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
+ Dropdown
+ </button>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop1">
+ <li><a href="#">Dropdown link</a></li>
+ <li><a href="#">Dropdown link</a></li>
+ </ul>
+ </div>
+ <button type="button" class="btn btn-secondary">Button</button>
+ <button type="button" class="btn btn-secondary">Button</button>
+ <div class="btn-group">
+ <button id="btnGroupVerticalDrop2" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
+ Dropdown
+ </button>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop2">
+ <li><a href="#">Dropdown link</a></li>
+ <li><a href="#">Dropdown link</a></li>
+ </ul>
+ </div>
+ <div class="btn-group">
+ <button id="btnGroupVerticalDrop3" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
+ Dropdown
+ </button>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop3">
+ <li><a href="#">Dropdown link</a></li>
+ <li><a href="#">Dropdown link</a></li>
+ </ul>
+ </div>
+ <div class="btn-group">
+ <button id="btnGroupVerticalDrop4" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
+ Dropdown
+ </button>
+ <ul class="dropdown-menu" role="menu" aria-labelledby="btnGroupVerticalDrop4">
+ <li><a href="#">Dropdown link</a></li>
+ <li><a href="#">Dropdown link</a></li>
+ </ul>
</div>
</div>
+</div>
+
{% highlight html %}
<div class="btn-group-vertical">
...
</div>
{% endhighlight %}
- <h3 id="btn-groups-justified">Justified button groups</h3>
- <p>Make a group of buttons stretch at equal sizes to span the entire width of its parent. Also works with button dropdowns within the button group.</p>
+### Justified button groups
- <div class="bs-callout bs-callout-warning">
- <h4>Handling borders</h4>
- <p>Due to the specific HTML and CSS used to justify buttons (namely <code>display: table-cell</code>), the borders between them are doubled. In regular button groups, <code>margin-left: -1px</code> is used to stack the borders instead of removing them. However, <code>margin</code> doesn't work with <code>display: table-cell</code>. As a result, depending on your customizations to Bootstrap, you may wish to remove or re-color the borders.</p>
- </div>
- <div class="bs-callout bs-callout-warning">
- <h4>IE8 and borders</h4>
- <p>Internet Explorer 8 doesn't render borders on buttons in a justified button group, whether it's on <code><a></code> or <code><button></code> elements. To get around that, wrap each button in another <code>.btn-group</code>.</p>
- <p>See <a href="https://github.com/twbs/bootstrap/issues/12476">#12476</a> for more information.</p>
- </div>
+Make a group of buttons stretch at equal sizes to span the entire width of its parent. Also works with button dropdowns within the button group.
- <h4>With <code><a></code> elements</h4>
- <p>Just wrap a series of <code>.btn</code>s in <code>.btn-group.btn-group-justified</code>.</p>
- <div class="bs-example">
- <div class="btn-group btn-group-justified">
- <a class="btn btn-secondary" role="button">Left</a>
- <a class="btn btn-secondary" role="button">Middle</a>
- <a class="btn btn-secondary" role="button">Right</a>
- </div>
- <br>
- <div class="btn-group btn-group-justified">
- <a class="btn btn-secondary" role="button">Left</a>
- <a class="btn btn-secondary" role="button">Middle</a>
- <div class="btn-group">
- <a class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
- Dropdown
- </a>
- <ul class="dropdown-menu" role="menu">
- <li><a href="#">Action</a></li>
- <li><a href="#">Another action</a></li>
- <li><a href="#">Something else here</a></li>
- <li class="divider"></li>
- <li><a href="#">Separated link</a></li>
- </ul>
- </div>
+<div class="bs-callout bs-callout-warning">
+ <h4>Handling borders</h4>
+ <p>Due to the specific HTML and CSS used to justify buttons (namely <code>display: table-cell</code>), the borders between them are doubled. In regular button groups, <code>margin-left: -1px</code> is used to stack the borders instead of removing them. However, <code>margin</code> doesn't work with <code>display: table-cell</code>. As a result, depending on your customizations to Bootstrap, you may wish to remove or re-color the borders.</p>
+</div>
+
+#### With `<a>` elements
+
+Just wrap a series of `.btn`s in `.btn-group.btn-group-justified`.
+
+<div class="bs-example">
+ <div class="btn-group btn-group-justified">
+ <a class="btn btn-secondary" role="button">Left</a>
+ <a class="btn btn-secondary" role="button">Middle</a>
+ <a class="btn btn-secondary" role="button">Right</a>
+ </div>
+ <br>
+ <div class="btn-group btn-group-justified">
+ <a class="btn btn-secondary" role="button">Left</a>
+ <a class="btn btn-secondary" role="button">Middle</a>
+ <div class="btn-group">
+ <a class="btn btn-secondary dropdown-toggle" data-toggle="dropdown">
+ Dropdown
+ </a>
+ <ul class="dropdown-menu" role="menu">
+ <li><a href="#">Action</a></li>
+ <li><a href="#">Another action</a></li>
+ <li><a href="#">Something else here</a></li>
+ <li class="divider"></li>
+ <li><a href="#">Separated link</a></li>
+ </ul>
</div>
</div>
+</div>
+
{% highlight html %}
<div class="btn-group btn-group-justified">
...
</div>
{% endhighlight %}
- <h4>With <code><button></code> elements</h4>
- <p>To use justified button groups with <code><button></code> elements, <strong class="text-danger">you must wrap each button in a button group</strong>. Most browsers don't properly apply our CSS for justification to <code><button></code> elements, but since we support button dropdowns, we can workaround that.</p>
- <div class="bs-example">
- <div class="btn-group btn-group-justified">
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">Left</button>
- </div>
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">Middle</button>
- </div>
- <div class="btn-group">
- <button type="button" class="btn btn-secondary">Right</button>
- </div>
+#### With `<button>` elements
+
+To use justified button groups with `<button>` elements, **you must wrap each button in a button group**. Most browsers don't properly apply our CSS for justification to `<button>` elements, but since we support button dropdowns, we can workaround that.
+
+<div class="bs-example">
+ <div class="btn-group btn-group-justified">
+ <div class="btn-group">
+ <button type="button" class="btn btn-secondary">Left</button>
+ </div>
+ <div class="btn-group">
+ <button type="button" class="btn btn-secondary">Middle</button>
+ </div>
+ <div class="btn-group">
+ <button type="button" class="btn btn-secondary">Right</button>
</div>
</div>
+</div>
+
{% highlight html %}
<div class="btn-group btn-group-justified">
<div class="btn-group">
@@ -257,4 +238,3 @@ title: Button group
</div>
</div>
{% endhighlight %}
-</div>