Docs: separate button group out of checks/radios, expand button groups page (#31201)

* Keep checks/radio toggle buttons on topic

- give examples of the pure toggle checks and radios, without the button group class. show that these work fine without `.btn-group`, but still cross-reference it
- move the explanation from "Checkbox toggle buttons" directly to "Toggle buttons", as the mention of using button classes applies equally to the subsequent "Radio toggle buttons" and "Outlined styles" subsections.

* Expand button group description

as it's not just single line, but vertical as well

* Expand button group examples

- add more colour ... `.btn-secondary` is just dull and uninspiring
- new section to showcase "Checkbox and radio button groups"
- add a mixed styles example
- add an example of vertical radio button group

2 files changed, 115 insertions, 69 deletions

diff --git a/site/content/docs/5.0/components/button-group.md b/site/content/docs/5.0/components/button-group.md
index af0ce9aa1..730faf2db 100644
--- a/site/content/docs/5.0/components/button-group.md
+++ b/site/content/docs/5.0/components/button-group.md
@@ -1,7 +1,7 @@
 ---
 layout: docs
 title: Button group
-description: Group a series of buttons together on a single line with the button group.
+description: Group a series of buttons together on a single line or stack them in a vertical column.
 group: components
 toc: true
 ---
@@ -12,9 +12,9 @@ Wrap a series of buttons with `.btn` in `.btn-group`.
 
 {{< example >}}
 <div class="btn-group" role="group" aria-label="Basic example">
-  <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>
+  <button type="button" class="btn btn-primary">Left</button>
+  <button type="button" class="btn btn-primary">Middle</button>
+  <button type="button" class="btn btn-primary">Right</button>
 </div>
 {{< /example >}}
 
@@ -30,19 +30,59 @@ These classes can also be added to groups of links, as an alternative to the [`.
 
 {{< example >}}
 <div class="btn-group">
-  <a href="#" class="btn btn-secondary active" aria-current="page">Active link</a>
-  <a href="#" class="btn btn-secondary">Link</a>
-  <a href="#" class="btn btn-secondary">Link</a>
+  <a href="#" class="btn btn-primary active" aria-current="page">Active link</a>
+  <a href="#" class="btn btn-primary">Link</a>
+  <a href="#" class="btn btn-primary">Link</a>
+</div>
+{{< /example >}}
+
+## Mixed styles
+
+{{< example >}}
+<div class="btn-group" role="group" aria-label="Basic mixed styles example">
+  <button type="button" class="btn btn-danger">Left</button>
+  <button type="button" class="btn btn-warning">Middle</button>
+  <button type="button" class="btn btn-success">Right</button>
 </div>
 {{< /example >}}
 
 ## Outlined styles
 
 {{< example >}}
-<div class="btn-group" role="group" aria-label="Basic example">
-  <button type="button" class="btn btn-outline-secondary">Left</button>
-  <button type="button" class="btn btn-outline-secondary">Middle</button>
-  <button type="button" class="btn btn-outline-secondary">Right</button>
+<div class="btn-group" role="group" aria-label="Basic outlined example">
+  <button type="button" class="btn btn-outline-primary">Left</button>
+  <button type="button" class="btn btn-outline-primary">Middle</button>
+  <button type="button" class="btn btn-outline-primary">Right</button>
+</div>
+{{< /example >}}
+
+## Checkbox and radio button groups
+
+Combine button-like checkbox and radio [toggle buttons]({{< docsref "/forms/checks-radios" >}}) into a seamless looking button group.
+
+{{< example >}}
+<div class="btn-group" role="group" aria-label="Basic checkbox toggle button group">
+  <input type="checkbox" class="btn-check" id="btncheck1" autocomplete="off">
+  <label class="btn btn-outline-primary" for="btncheck1">Checkbox 1</label>
+
+  <input type="checkbox" class="btn-check" id="btncheck2" autocomplete="off">
+  <label class="btn btn-outline-primary" for="btncheck2">Checkbox 2</label>
+
+  <input type="checkbox" class="btn-check" id="btncheck3" autocomplete="off">
+  <label class="btn btn-outline-primary" for="btncheck3">Checkbox 3</label>
+</div>
+{{< /example >}}
+
+{{< example >}}
+<div class="btn-group" role="group" aria-label="Basic radio toggle button group">
+  <input type="radio" class="btn-check" name="btnradio" id="btnradio1" autocomplete="off" checked>
+  <label class="btn btn-outline-primary" for="btnradio1">Radio 1</label>
+
+  <input type="radio" class="btn-check" name="btnradio" id="btnradio2" autocomplete="off">
+  <label class="btn btn-outline-primary" for="btnradio2">Radio 2</label>
+
+  <input type="radio" class="btn-check" name="btnradio" id="btnradio3" autocomplete="off">
+  <label class="btn btn-outline-primary" for="btnradio3">Radio 3</label>
 </div>
 {{< /example >}}
 
@@ -53,10 +93,10 @@ Combine sets of button groups into button toolbars for more complex components.
 {{< example >}}
 <div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
   <div class="btn-group mr-2" role="group" aria-label="First 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>
+    <button type="button" class="btn btn-primary">1</button>
+    <button type="button" class="btn btn-primary">2</button>
+    <button type="button" class="btn btn-primary">3</button>
+    <button type="button" class="btn btn-primary">4</button>
   </div>
   <div class="btn-group mr-2" role="group" aria-label="Second group">
     <button type="button" class="btn btn-secondary">5</button>
@@ -64,7 +104,7 @@ Combine sets of button groups into button toolbars for more complex components.
     <button type="button" class="btn btn-secondary">7</button>
   </div>
   <div class="btn-group" role="group" aria-label="Third group">
-    <button type="button" class="btn btn-secondary">8</button>
+    <button type="button" class="btn btn-info">8</button>
   </div>
 </div>
 {{< /example >}}
@@ -74,10 +114,10 @@ Feel free to mix input groups with button groups in your toolbars. Similar to th
 {{< example >}}
 <div class="btn-toolbar mb-3" role="toolbar" aria-label="Toolbar with button groups">
   <div class="btn-group mr-2" role="group" aria-label="First 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>
+    <button type="button" class="btn btn-outline-secondary">1</button>
+    <button type="button" class="btn btn-outline-secondary">2</button>
+    <button type="button" class="btn btn-outline-secondary">3</button>
+    <button type="button" class="btn btn-outline-secondary">4</button>
   </div>
   <div class="input-group">
     <div class="input-group-text" id="btnGroupAddon">@</div>
@@ -87,10 +127,10 @@ Feel free to mix input groups with button groups in your toolbars. Similar to th
 
 <div class="btn-toolbar justify-content-between" role="toolbar" aria-label="Toolbar with button groups">
   <div class="btn-group" role="group" aria-label="First 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>
+    <button type="button" class="btn btn-outline-secondary">1</button>
+    <button type="button" class="btn btn-outline-secondary">2</button>
+    <button type="button" class="btn btn-outline-secondary">3</button>
+    <button type="button" class="btn btn-outline-secondary">4</button>
   </div>
   <div class="input-group">
     <div class="input-group-text" id="btnGroupAddon2">@</div>
@@ -105,21 +145,21 @@ Instead of applying button sizing classes to every button in a group, just add `
 
 <div class="bd-example">
   <div class="btn-group btn-group-lg" role="group" aria-label="Large button 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>
+    <button type="button" class="btn btn-outline-dark">Left</button>
+    <button type="button" class="btn btn-outline-dark">Middle</button>
+    <button type="button" class="btn btn-outline-dark">Right</button>
   </div>
   <br>
   <div class="btn-group" role="group" aria-label="Default button 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>
+    <button type="button" class="btn btn-outline-dark">Left</button>
+    <button type="button" class="btn btn-outline-dark">Middle</button>
+    <button type="button" class="btn btn-outline-dark">Right</button>
   </div>
   <br>
   <div class="btn-group btn-group-sm" role="group" aria-label="Small button 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>
+    <button type="button" class="btn btn-outline-dark">Left</button>
+    <button type="button" class="btn btn-outline-dark">Middle</button>
+    <button type="button" class="btn btn-outline-dark">Right</button>
   </div>
 </div>
 
@@ -135,11 +175,11 @@ Place a `.btn-group` within another `.btn-group` when you want dropdown menus mi
 
 {{< example >}}
 <div class="btn-group" role="group" aria-label="Button group with nested dropdown">
-  <button type="button" class="btn btn-secondary">1</button>
-  <button type="button" class="btn btn-secondary">2</button>
+  <button type="button" class="btn btn-primary">1</button>
+  <button type="button" class="btn btn-primary">2</button>
 
   <div class="btn-group" role="group">
-    <button id="btnGroupDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
+    <button id="btnGroupDrop1" type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
       Dropdown
     </button>
     <ul class="dropdown-menu" aria-labelledby="btnGroupDrop1">
@@ -156,22 +196,21 @@ Make a set of buttons appear vertically stacked rather than horizontally. **Spli
 
 <div class="bd-example">
   <div class="btn-group-vertical" role="group" aria-label="Vertical button group">
-    <button type="button" class="btn btn-secondary">Button</button>
-    <button type="button" class="btn btn-secondary">Button</button>
-    <button type="button" class="btn btn-secondary">Button</button>
-    <button type="button" class="btn btn-secondary">Button</button>
-    <button type="button" class="btn btn-secondary">Button</button>
-    <button type="button" class="btn btn-secondary">Button</button>
+    <button type="button" class="btn btn-dark">Button</button>
+    <button type="button" class="btn btn-dark">Button</button>
+    <button type="button" class="btn btn-dark">Button</button>
+    <button type="button" class="btn btn-dark">Button</button>
+    <button type="button" class="btn btn-dark">Button</button>
+    <button type="button" class="btn btn-dark">Button</button>
   </div>
 </div>
 
-
 <div class="bd-example">
   <div class="btn-group-vertical" role="group" aria-label="Vertical button group">
-    <button type="button" class="btn btn-secondary">Button</button>
-    <button type="button" class="btn btn-secondary">Button</button>
+    <button type="button" class="btn btn-primary">Button</button>
+    <button type="button" class="btn btn-primary">Button</button>
     <div class="btn-group" role="group">
-      <button id="btnGroupVerticalDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
+      <button id="btnGroupVerticalDrop1" type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
         Dropdown
       </button>
       <ul class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop1">
@@ -179,10 +218,10 @@ Make a set of buttons appear vertically stacked rather than horizontally. **Spli
         <li><a class="dropdown-item" 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>
+    <button type="button" class="btn btn-primary">Button</button>
+    <button type="button" class="btn btn-primary">Button</button>
     <div class="btn-group" role="group">
-      <button id="btnGroupVerticalDrop2" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
+      <button id="btnGroupVerticalDrop2" type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
         Dropdown
       </button>
       <ul class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop2">
@@ -191,7 +230,7 @@ Make a set of buttons appear vertically stacked rather than horizontally. **Spli
       </ul>
     </div>
     <div class="btn-group" role="group">
-      <button id="btnGroupVerticalDrop3" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
+      <button id="btnGroupVerticalDrop3" type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
         Dropdown
       </button>
       <ul class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop3">
@@ -200,7 +239,7 @@ Make a set of buttons appear vertically stacked rather than horizontally. **Spli
       </ul>
     </div>
     <div class="btn-group" role="group">
-      <button id="btnGroupVerticalDrop4" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
+      <button id="btnGroupVerticalDrop4" type="button" class="btn btn-primary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
         Dropdown
       </button>
       <ul class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop4">
@@ -211,6 +250,17 @@ Make a set of buttons appear vertically stacked rather than horizontally. **Spli
   </div>
 </div>
 
+<div class="bd-example">
+  <div class="btn-group-vertical" role="group" aria-label="Vertical radio toggle button group">
+    <input type="radio" class="btn-check" name="vbtn-radio" id="vbtn-radio1" autocomplete="off" checked>
+    <label class="btn btn-outline-danger" for="vbtn-radio1">Radio 1</label>
+    <input type="radio" class="btn-check" name="vbtn-radio" id="vbtn-radio2" autocomplete="off">
+    <label class="btn btn-outline-danger" for="vbtn-radio2">Radio 2</label>
+    <input type="radio" class="btn-check" name="vbtn-radio" id="vbtn-radio3" autocomplete="off">
+    <label class="btn btn-outline-danger" for="vbtn-radio3">Radio 3</label>
+  </div>
+</div>
+
 {{< highlight html >}}
 <div class="btn-group-vertical">
   ...
diff --git a/site/content/docs/5.0/forms/checks-radios.md b/site/content/docs/5.0/forms/checks-radios.md
index 8de3d4336..c8d59e3cf 100644
--- a/site/content/docs/5.0/forms/checks-radios.md
+++ b/site/content/docs/5.0/forms/checks-radios.md
@@ -213,9 +213,9 @@ Omit the wrapping `.form-check` for checkboxes and radios that have no label tex
 
 ## Toggle buttons
 
-### Checkbox toggle buttons
+Create button-like checkboxes and radio buttons by using `.btn` styles rather than `.form-check-label` on the `<label>` elements. These toggle buttons can further be grouped in a [button group]({{< docsref "/components/button-group" >}}) if needed.
 
-Bootstrap's `.btn` styles can be applied to `<label>`s, to provide checkbox style button toggling. Add an input with a `.btn-check` class as previous sibling to toggle the input state.
+### Checkbox toggle buttons
 
 {{< example >}}
 <input type="checkbox" class="btn-check" id="btn-check" autocomplete="off">
@@ -233,23 +233,21 @@ Visually, these checkbox toggle buttons are identical to the [button plugin togg
 
 ### Radio toggle buttons
 
-Toggle buttons can be grouped in a [button group]({{< docsref "/components/button-group" >}}) if needed.
-
 {{< example >}}
-<div class="btn-group">
-  <input type="radio" class="btn-check" name="options" id="option1" autocomplete="off" checked>
-  <label class="btn btn-secondary" for="option1">Checked</label>
+<input type="radio" class="btn-check" name="options" id="option1" autocomplete="off" checked>
+<label class="btn btn-secondary" for="option1">Checked</label>
 
-  <input type="radio" class="btn-check" name="options" id="option2" autocomplete="off">
-  <label class="btn btn-secondary" for="option2">Radio</label>
+<input type="radio" class="btn-check" name="options" id="option2" autocomplete="off">
+<label class="btn btn-secondary" for="option2">Radio</label>
 
-  <input type="radio" class="btn-check" name="options" id="option3" autocomplete="off">
-  <label class="btn btn-secondary" for="option3">Radio</label>
-</div>
+<input type="radio" class="btn-check" name="options" id="option3" autocomplete="off">
+<label class="btn btn-secondary" for="option3">Radio</label>
 {{< /example >}}
 
 ### Outlined styles
 
+Different variants of `.btn`, such at the various outlined styles, are supported.
+
 {{< example >}}
 <input type="checkbox" class="btn-check" id="btn-check-outlined" autocomplete="off">
 <label class="btn btn-outline-primary" for="btn-check-outlined">Single toggle</label><br>
@@ -257,11 +255,9 @@ Toggle buttons can be grouped in a [button group]({{< docsref "/components/butto
 <input type="checkbox" class="btn-check" id="btn-check-2-outlined" checked autocomplete="off">
 <label class="btn btn-outline-secondary" for="btn-check-2-outlined">Checked</label><br>
 
-<div class="btn-group">
-  <input type="radio" class="btn-check" name="options-outlined" id="success-outlined" autocomplete="off" checked>
-  <label class="btn btn-outline-success" for="success-outlined">Checked success radio</label>
+<input type="radio" class="btn-check" name="options-outlined" id="success-outlined" autocomplete="off" checked>
+<label class="btn btn-outline-success" for="success-outlined">Checked success radio</label>
 
-  <input type="radio" class="btn-check" name="options-outlined" id="danger-outlined" autocomplete="off">
-  <label class="btn btn-outline-danger" for="danger-outlined">Danger radio</label>
-</div>
+<input type="radio" class="btn-check" name="options-outlined" id="danger-outlined" autocomplete="off">
+<label class="btn btn-outline-danger" for="danger-outlined">Danger radio</label>
 {{< /example >}}