src/scss/bootstrap-4.0.0-alpha.6/docs/components/input-group.md

   1 ---
   2 layout: docs
   3 title: Input group
   4 description: Extend form controls with the input group.
   5 group: components
   6 ---
   7
   8 Easily extend form controls by adding text, buttons, or button groups on either side of textual `<input>`s.
   9
  10 ## Contents
  11
  12 * Will be replaced with the ToC, excluding the "Contents" header
  13 {:toc}
  14
  15 ## Basic example
  16
  17 Place one add-on or button on either side of an input. You may also place one on both sides of an input. **We do not support multiple form-controls in a single input group.**
  18
  19 {% example html %}
  20 <div class="input-group">
  21   <span class="input-group-addon" id="basic-addon1">@</span>
  22   <input type="text" class="form-control" placeholder="Username" aria-describedby="basic-addon1">
  23 </div>
  24 <br>
  25 <div class="input-group">
  26   <input type="text" class="form-control" placeholder="Recipient's username" aria-describedby="basic-addon2">
  27   <span class="input-group-addon" id="basic-addon2">@example.com</span>
  28 </div>
  29 <br>
  30 <label for="basic-url">Your vanity URL</label>
  31 <div class="input-group">
  32   <span class="input-group-addon" id="basic-addon3">https://example.com/users/</span>
  33   <input type="text" class="form-control" id="basic-url" aria-describedby="basic-addon3">
  34 </div>
  35 <br>
  36 <div class="input-group">
  37   <span class="input-group-addon">$</span>
  38   <input type="text" class="form-control" aria-label="Amount (to the nearest dollar)">
  39   <span class="input-group-addon">.00</span>
  40 </div>
  41 <br>
  42 <div class="input-group">
  43   <span class="input-group-addon">$</span>
  44   <span class="input-group-addon">0.00</span>
  45   <input type="text" class="form-control" aria-label="Amount (to the nearest dollar)">
  46 </div>
  47 {% endexample %}
  48
  49 ## Sizing
  50
  51 Add the relative form sizing classes to the `.input-group` itself and contents within will automatically resize—no need for repeating the form control size classes on each element.
  52
  53 {% example html %}
  54 <div class="input-group input-group-lg">
  55   <span class="input-group-addon" id="sizing-addon1">@</span>
  56   <input type="text" class="form-control" placeholder="Username" aria-describedby="sizing-addon1">
  57 </div>
  58 <br>
  59 <div class="input-group">
  60   <span class="input-group-addon" id="sizing-addon2">@</span>
  61   <input type="text" class="form-control" placeholder="Username" aria-describedby="sizing-addon2">
  62 </div>
  63 {% endexample %}
  64
  65 ## Checkboxes and radio addons
  66
  67 Place any checkbox or radio option within an input group's addon instead of text.
  68
  69 {% example html %}
  70 <div class="row">
  71   <div class="col-lg-6">
  72     <div class="input-group">
  73       <span class="input-group-addon">
  74         <input type="checkbox" aria-label="Checkbox for following text input">
  75       </span>
  76       <input type="text" class="form-control" aria-label="Text input with checkbox">
  77     </div>
  78   </div>
  79   <div class="col-lg-6">
  80     <div class="input-group">
  81       <span class="input-group-addon">
  82         <input type="radio" aria-label="Radio button for following text input">
  83       </span>
  84       <input type="text" class="form-control" aria-label="Text input with radio button">
  85     </div>
  86   </div>
  87 </div>
  88 {% endexample %}
  89
  90 ## Multiple addons
  91
  92 Multiple add-ons are supported and can be mixed with checkbox and radio input versions.
  93
  94 {% example html %}
  95 <div class="row">
  96   <div class="col-lg-6">
  97     <div class="input-group">
  98       <span class="input-group-addon">
  99         <input type="checkbox" aria-label="Checkbox for following text input">
 100       </span>
 101       <span class="input-group-addon">$</span>
 102       <input type="text" class="form-control" aria-label="Text input with checkbox">
 103     </div>
 104   </div>
 105   <div class="col-lg-6">
 106     <div class="input-group">
 107       <span class="input-group-addon">$</span>
 108       <span class="input-group-addon">0.00</span>
 109       <input type="text" class="form-control" aria-label="Text input with radio button">
 110     </div>
 111   </div>
 112 </div>
 113 {% endexample %}
 114
 115
 116 ## Button addons
 117
 118 Buttons in input groups must wrapped in a `.input-group-btn` for proper alignment and sizing. This is required due to default browser styles that cannot be overridden.
 119
 120 {% example html %}
 121 <div class="row">
 122   <div class="col-lg-6">
 123     <div class="input-group">
 124       <span class="input-group-btn">
 125         <button class="btn btn-secondary" type="button">Go!</button>
 126       </span>
 127       <input type="text" class="form-control" placeholder="Search for...">
 128     </div>
 129   </div>
 130   <div class="col-lg-6">
 131     <div class="input-group">
 132       <input type="text" class="form-control" placeholder="Search for...">
 133       <span class="input-group-btn">
 134         <button class="btn btn-secondary" type="button">Go!</button>
 135       </span>
 136     </div>
 137   </div>
 138 </div>
 139 <br>
 140 <div class="row">
 141   <div class="col-lg-offset-3 col-lg-6">
 142     <div class="input-group">
 143       <span class="input-group-btn">
 144         <button class="btn btn-secondary" type="button">Hate it</button>
 145       </span>
 146       <input type="text" class="form-control" placeholder="Product name">
 147       <span class="input-group-btn">
 148         <button class="btn btn-secondary" type="button">Love it</button>
 149       </span>
 150     </div>
 151   </div>
 152 </div>
 153 {% endexample %}
 154
 155 ## Buttons with dropdowns
 156
 157 {% example html %}
 158 <div class="row">
 159   <div class="col-lg-6">
 160     <div class="input-group">
 161       <div class="input-group-btn">
 162         <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 163           Action
 164         </button>
 165         <div class="dropdown-menu">
 166           <a class="dropdown-item" href="#">Action</a>
 167           <a class="dropdown-item" href="#">Another action</a>
 168           <a class="dropdown-item" href="#">Something else here</a>
 169           <div role="separator" class="dropdown-divider"></div>
 170           <a class="dropdown-item" href="#">Separated link</a>
 171         </div>
 172       </div>
 173       <input type="text" class="form-control" aria-label="Text input with dropdown button">
 174     </div>
 175   </div>
 176   <div class="col-lg-6">
 177     <div class="input-group">
 178       <input type="text" class="form-control" aria-label="Text input with dropdown button">
 179       <div class="input-group-btn">
 180         <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 181           Action
 182         </button>
 183         <div class="dropdown-menu dropdown-menu-right">
 184           <a class="dropdown-item" href="#">Action</a>
 185           <a class="dropdown-item" href="#">Another action</a>
 186           <a class="dropdown-item" href="#">Something else here</a>
 187           <div role="separator" class="dropdown-divider"></div>
 188           <a class="dropdown-item" href="#">Separated link</a>
 189         </div>
 190       </div>
 191     </div>
 192   </div>
 193 </div>
 194 {% endexample %}
 195
 196 ## Segmented buttons
 197
 198 {% example html %}
 199 <div class="row">
 200   <div class="col-lg-6">
 201     <div class="input-group">
 202       <div class="input-group-btn">
 203         <button type="button" class="btn btn-secondary">Action</button>
 204         <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 205           <span class="sr-only">Toggle Dropdown</span>
 206         </button>
 207         <div class="dropdown-menu">
 208           <a class="dropdown-item" href="#">Action</a>
 209           <a class="dropdown-item" href="#">Another action</a>
 210           <a class="dropdown-item" href="#">Something else here</a>
 211           <div role="separator" class="dropdown-divider"></div>
 212           <a class="dropdown-item" href="#">Separated link</a>
 213         </div>
 214       </div>
 215       <input type="text" class="form-control" aria-label="Text input with segmented button dropdown">
 216     </div>
 217   </div>
 218   <div class="col-lg-6">
 219     <div class="input-group">
 220       <input type="text" class="form-control" aria-label="Text input with segmented button dropdown">
 221       <div class="input-group-btn">
 222         <button type="button" class="btn btn-secondary">Action</button>
 223         <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
 224           <span class="sr-only">Toggle Dropdown</span>
 225         </button>
 226         <div class="dropdown-menu dropdown-menu-right">
 227           <a class="dropdown-item" href="#">Action</a>
 228           <a class="dropdown-item" href="#">Another action</a>
 229           <a class="dropdown-item" href="#">Something else here</a>
 230           <div role="separator" class="dropdown-divider"></div>
 231           <a class="dropdown-item" href="#">Separated link</a>
 232         </div>
 233       </div>
 234     </div>
 235   </div>
 236 </div>
 237 {% endexample %}
 238
 239 ## Accessibility
 240
 241 Screen readers will have trouble with your forms if you don't include a label for every input. For these input groups, ensure that any additional label or functionality is conveyed to assistive technologies.
 242
 243 The exact technique to be used (`<label>` elements hidden using the `.sr-only` class, or use of the `aria-label`, `aria-labelledby`, `aria-describedby`, `title` or `placeholder` attribute) and what additional information will need to be conveyed will vary depending on the exact type of interface widget you're implementing. The examples in this section provide a few suggested, case-specific approaches.