static/scss/bootstrap-4.0.0-alpha.6/docs/components/button-group.md

   1 ---
   2 layout: docs
   3 title: Button group
   4 description: Group a series of buttons together on a single line with the button group, and super-power them with JavaScript.
   5 group: components
   6 ---
   7
   8 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]({{ site.baseurl }}/components/buttons/#button-plugin).
   9
  10 ## Contents
  11
  12 * Will be replaced with the ToC, excluding the "Contents" header
  13 {:toc}
  14
  15 ## Basic example
  16
  17 Wrap a series of buttons with `.btn` in `.btn-group`.
  18
  19 {% example html %}
  20 <div class="btn-group" role="group" aria-label="Basic example">
  21   <button type="button" class="btn btn-secondary">Left</button>
  22   <button type="button" class="btn btn-secondary">Middle</button>
  23   <button type="button" class="btn btn-secondary">Right</button>
  24 </div>
  25 {% endexample %}
  26
  27 ## Button toolbar
  28
  29 Combine sets of button groups into button toolbars for more complex components. Use utility classes as needed to space out groups, buttons, and more.
  30
  31 {% example html %}
  32 <div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
  33   <div class="btn-group mr-2" role="group" aria-label="First group">
  34     <button type="button" class="btn btn-secondary">1</button>
  35     <button type="button" class="btn btn-secondary">2</button>
  36     <button type="button" class="btn btn-secondary">3</button>
  37     <button type="button" class="btn btn-secondary">4</button>
  38   </div>
  39   <div class="btn-group mr-2" role="group" aria-label="Second group">
  40     <button type="button" class="btn btn-secondary">5</button>
  41     <button type="button" class="btn btn-secondary">6</button>
  42     <button type="button" class="btn btn-secondary">7</button>
  43   </div>
  44   <div class="btn-group" role="group" aria-label="Third group">
  45     <button type="button" class="btn btn-secondary">8</button>
  46   </div>
  47 </div>
  48 {% endexample %}
  49
  50 Feel free to mix input groups with button groups in your toolbars. Similar to the example above, you'll likely need some utilities though to space things properly.
  51
  52 {% example html %}
  53 <div class="btn-toolbar mb-3" role="toolbar" aria-label="Toolbar with button groups">
  54   <div class="btn-group mr-2" role="group" aria-label="First group">
  55     <button type="button" class="btn btn-secondary">1</button>
  56     <button type="button" class="btn btn-secondary">2</button>
  57     <button type="button" class="btn btn-secondary">3</button>
  58     <button type="button" class="btn btn-secondary">4</button>
  59   </div>
  60   <div class="input-group">
  61     <span class="input-group-addon" id="btnGroupAddon">@</span>
  62     <input type="text" class="form-control" placeholder="Input group example" aria-describedby="btnGroupAddon">
  63   </div>
  64 </div>
  65
  66 <div class="btn-toolbar justify-content-between" role="toolbar" aria-label="Toolbar with button groups">
  67   <div class="btn-group" role="group" aria-label="First group">
  68     <button type="button" class="btn btn-secondary">1</button>
  69     <button type="button" class="btn btn-secondary">2</button>
  70     <button type="button" class="btn btn-secondary">3</button>
  71     <button type="button" class="btn btn-secondary">4</button>
  72   </div>
  73   <div class="input-group">
  74     <span class="input-group-addon" id="btnGroupAddon2">@</span>
  75     <input type="text" class="form-control" placeholder="Input group example" aria-describedby="btnGroupAddon2">
  76   </div>
  77 </div>
  78 {% endexample %}
  79
  80 ## Sizing
  81
  82 Instead of applying button sizing classes to every button in a group, just add `.btn-group-*` to each `.btn-group`, including each one when nesting multiple groups.
  83
  84 <div class="bd-example">
  85   <div class="btn-group btn-group-lg" role="group" aria-label="Large button group">
  86     <button type="button" class="btn btn-secondary">Left</button>
  87     <button type="button" class="btn btn-secondary">Middle</button>
  88     <button type="button" class="btn btn-secondary">Right</button>
  89   </div>
  90   <br>
  91   <div class="btn-group" role="group" aria-label="Default button group">
  92     <button type="button" class="btn btn-secondary">Left</button>
  93     <button type="button" class="btn btn-secondary">Middle</button>
  94     <button type="button" class="btn btn-secondary">Right</button>
  95   </div>
  96   <br>
  97   <div class="btn-group btn-group-sm" role="group" aria-label="Small button group">
  98     <button type="button" class="btn btn-secondary">Left</button>
  99     <button type="button" class="btn btn-secondary">Middle</button>
 100     <button type="button" class="btn btn-secondary">Right</button>
 101   </div>
 102 </div>
 103
 104 {% highlight html %}
 105 <div class="btn-group btn-group-lg" role="group" aria-label="...">...</div>
 106 <div class="btn-group" role="group" aria-label="...">...</div>
 107 <div class="btn-group btn-group-sm" role="group" aria-label="...">...</div>
 108 {% endhighlight %}
 109
 110 ## Nesting
 111
 112 Place a `.btn-group` within another `.btn-group` when you want dropdown menus mixed with a series of buttons.
 113
 114 {% example html %}
 115 <div class="btn-group" role="group" aria-label="Button group with nested dropdown">
 116   <button type="button" class="btn btn-secondary">1</button>
 117   <button type="button" class="btn btn-secondary">2</button>
 118
 119   <div class="btn-group" role="group">
 120     <button id="btnGroupDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 121       Dropdown
 122     </button>
 123     <div class="dropdown-menu" aria-labelledby="btnGroupDrop1">
 124       <a class="dropdown-item" href="#">Dropdown link</a>
 125       <a class="dropdown-item" href="#">Dropdown link</a>
 126     </div>
 127   </div>
 128 </div>
 129 {% endexample %}
 130
 131 ## Vertical variation
 132
 133 Make a set of buttons appear vertically stacked rather than horizontally. **Split button dropdowns are not supported here.**
 134
 135 <div class="bd-example">
 136   <div class="btn-group-vertical" role="group" aria-label="Vertical button group">
 137     <button type="button" class="btn btn-secondary">Button</button>
 138     <button type="button" class="btn btn-secondary">Button</button>
 139     <button type="button" class="btn btn-secondary">Button</button>
 140     <button type="button" class="btn btn-secondary">Button</button>
 141     <button type="button" class="btn btn-secondary">Button</button>
 142     <button type="button" class="btn btn-secondary">Button</button>
 143   </div>
 144 </div>
 145
 146
 147 <div class="bd-example">
 148   <div class="btn-group-vertical" role="group" aria-label="Vertical button group">
 149     <button type="button" class="btn btn-secondary">Button</button>
 150     <button type="button" class="btn btn-secondary">Button</button>
 151     <div class="btn-group" role="group">
 152       <button id="btnGroupVerticalDrop1" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 153         Dropdown
 154       </button>
 155       <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop1">
 156         <a class="dropdown-item" href="#">Dropdown link</a>
 157         <a class="dropdown-item" href="#">Dropdown link</a>
 158       </div>
 159     </div>
 160     <button type="button" class="btn btn-secondary">Button</button>
 161     <button type="button" class="btn btn-secondary">Button</button>
 162     <div class="btn-group" role="group">
 163       <button id="btnGroupVerticalDrop2" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 164         Dropdown
 165       </button>
 166       <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop2">
 167         <a class="dropdown-item" href="#">Dropdown link</a>
 168         <a class="dropdown-item" href="#">Dropdown link</a>
 169       </div>
 170     </div>
 171     <div class="btn-group" role="group">
 172       <button id="btnGroupVerticalDrop3" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 173         Dropdown
 174       </button>
 175       <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop3">
 176         <a class="dropdown-item" href="#">Dropdown link</a>
 177         <a class="dropdown-item" href="#">Dropdown link</a>
 178       </div>
 179     </div>
 180     <div class="btn-group" role="group">
 181       <button id="btnGroupVerticalDrop4" type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 182         Dropdown
 183       </button>
 184       <div class="dropdown-menu" aria-labelledby="btnGroupVerticalDrop4">
 185         <a class="dropdown-item" href="#">Dropdown link</a>
 186         <a class="dropdown-item" href="#">Dropdown link</a>
 187       </div>
 188     </div>
 189   </div>
 190 </div>
 191
 192 {% highlight html %}
 193 <div class="btn-group-vertical">
 194   ...
 195 </div>
 196 {% endhighlight %}
 197
 198 ## Tooltips and popovers
 199
 200 Due to the specific implementation (and some other components), a bit of special casing is required for tooltips and popovers within button groups. **You'll have to specify the option `container: 'body'`** to avoid unwanted side effects (such as the element growing wider and/or losing its rounded corners when the tooltip or popover is triggered).