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

   1 ---
   2 layout: docs
   3 title: Buttons
   4 description: Use Bootstrap's custom button styles for actions in forms, dialogs, and more with support for multiple sizes, states, and more.
   5 group: components
   6 redirect_from: "/components/"
   7 ---
   8
   9 Use Bootstrap's custom button styles for actions in forms, dialogs, and more. Includes support for a handful of contextual variations, sizes, states, and more.
  10
  11 ## Contents
  12
  13 * Will be replaced with the ToC, excluding the "Contents" header
  14 {:toc}
  15
  16 ## Examples
  17
  18 Bootstrap includes six predefined button styles, each serving its own semantic purpose.
  19
  20 {% example html %}
  21 <!-- Provides extra visual weight and identifies the primary action in a set of buttons -->
  22 <button type="button" class="btn btn-primary">Primary</button>
  23
  24 <!-- Secondary, outline button -->
  25 <button type="button" class="btn btn-secondary">Secondary</button>
  26
  27 <!-- Indicates a successful or positive action -->
  28 <button type="button" class="btn btn-success">Success</button>
  29
  30 <!-- Contextual button for informational alert messages -->
  31 <button type="button" class="btn btn-info">Info</button>
  32
  33 <!-- Indicates caution should be taken with this action -->
  34 <button type="button" class="btn btn-warning">Warning</button>
  35
  36 <!-- Indicates a dangerous or potentially negative action -->
  37 <button type="button" class="btn btn-danger">Danger</button>
  38
  39 <!-- Deemphasize a button by making it look like a link while maintaining button behavior -->
  40 <button type="button" class="btn btn-link">Link</button>
  41 {% endexample %}
  42
  43 {% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %}
  44 {{ callout-include | markdownify }}
  45
  46 ## Button tags
  47
  48 The `.btn` classes are designed to be used with the `<button>` element. However, you can also use these classes on `<a>` or `<input>` elements (though some browsers may apply a slightly different rendering).
  49
  50 When using button classes on `<a>` elements that are used to trigger in-page functionality (like collapsing content), rather than linking to new pages or sections within the current page, these links should be given a `role="button"` to appropriately convey their purpose to assistive technologies such as screen readers.
  51
  52 {% example html %}
  53 <a class="btn btn-primary" href="#" role="button">Link</a>
  54 <button class="btn btn-primary" type="submit">Button</button>
  55 <input class="btn btn-primary" type="button" value="Input">
  56 <input class="btn btn-primary" type="submit" value="Submit">
  57 <input class="btn btn-primary" type="reset" value="Reset">
  58 {% endexample %}
  59
  60 ## Outline buttons
  61
  62 In need of a button, but not the hefty background colors they bring? Replace the default modifier classes with the `.btn-outline-*` ones to remove all background images and colors on any button.
  63
  64 {% example html %}
  65 <button type="button" class="btn btn-outline-primary">Primary</button>
  66 <button type="button" class="btn btn-outline-secondary">Secondary</button>
  67 <button type="button" class="btn btn-outline-success">Success</button>
  68 <button type="button" class="btn btn-outline-info">Info</button>
  69 <button type="button" class="btn btn-outline-warning">Warning</button>
  70 <button type="button" class="btn btn-outline-danger">Danger</button>
  71 {% endexample %}
  72
  73
  74 ## Sizes
  75
  76 Fancy larger or smaller buttons? Add `.btn-lg` or `.btn-sm` for additional sizes.
  77
  78 {% example html %}
  79 <button type="button" class="btn btn-primary btn-lg">Large button</button>
  80 <button type="button" class="btn btn-secondary btn-lg">Large button</button>
  81 {% endexample %}
  82
  83 {% example html %}
  84 <button type="button" class="btn btn-primary btn-sm">Small button</button>
  85 <button type="button" class="btn btn-secondary btn-sm">Small button</button>
  86 {% endexample %}
  87
  88 Create block level buttons—those that span the full width of a parent—by adding `.btn-block`.
  89
  90 {% example html %}
  91 <button type="button" class="btn btn-primary btn-lg btn-block">Block level button</button>
  92 <button type="button" class="btn btn-secondary btn-lg btn-block">Block level button</button>
  93 {% endexample %}
  94
  95 ## Active state
  96
  97 Buttons will appear pressed (with a darker background, darker border, and inset shadow) when active. **There's no need to add a class to `<button>`s as they use a pseudo-class**. However, you can still force the same active appearance with `.active` (and include the <code>aria-pressed="true"</code> attribute) should you need to replicate the state programmatically.
  98
  99 {% example html %}
 100 <a href="#" class="btn btn-primary btn-lg active" role="button" aria-pressed="true">Primary link</a>
 101 <a href="#" class="btn btn-secondary btn-lg active" role="button" aria-pressed="true">Link</a>
 102 {% endexample %}
 103
 104 ## Disabled state
 105
 106 Make buttons look inactive by adding the `disabled` boolean attribute to any `<button>` element.
 107
 108 {% example html %}
 109 <button type="button" class="btn btn-lg btn-primary" disabled>Primary button</button>
 110 <button type="button" class="btn btn-secondary btn-lg" disabled>Button</button>
 111 {% endexample %}
 112
 113 Disabled buttons using the `<a>` element behave a bit different:
 114
 115 - `<a>`s don't support the `disabled` attribute, so you must add the `.disabled` class to make it visually appear disabled.
 116 - Some future-friendly styles are included to disable all `pointer-events` on anchor buttons. In browsers which support that property, you won't see the disabled cursor at all.
 117 - Disabled buttons should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies.
 118
 119 {% example html %}
 120 <a href="#" class="btn btn-primary btn-lg disabled" role="button" aria-disabled="true">Primary link</a>
 121 <a href="#" class="btn btn-secondary btn-lg disabled" role="button" aria-disabled="true">Link</a>
 122 {% endexample %}
 123
 124 {% callout warning %}
 125 #### Link functionality caveat
 126
 127 The `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s, but that CSS property is not yet standardized. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, add a `tabindex="-1"` attribute on these links (to prevent them from receiving keyboard focus) and use custom JavaScript to disable their functionality.
 128 {% endcallout %}
 129
 130 ## Button plugin
 131
 132 Do more with buttons. Control button states or create groups of buttons for more components like toolbars.
 133
 134 ### Toggle states
 135
 136 Add `data-toggle="button"` to toggle a button's `active` state. If you're pre-toggling a button, you must manually add the `.active` class **and** `aria-pressed="true"` to the `<button>`.
 137
 138 {% example html %}
 139 <button type="button" class="btn btn-primary" data-toggle="button" aria-pressed="false" autocomplete="off">
 140   Single toggle
 141 </button>
 142 {% endexample %}
 143
 144 ### Checkbox and radio buttons
 145
 146 Bootstrap's `.button` styles can be applied to other elements, such as `<label>`s, to provide checkbox or radio style button toggling. Add `data-toggle="buttons"` to a `.btn-group` containing those modified buttons to enable toggling in their respective styles.
 147
 148 The checked state for these buttons is **only updated via `click` event** on the button. If you use another method to update the input—e.g., with `<input type="reset">` or by manually applying the input's `checked` property—you'll need to toggle `.active` on the `<label>` manually.
 149
 150 Note that pre-checked buttons require you to manually add the `.active` class to the input's `<label>`.
 151
 152 {% example html %}
 153 <div class="btn-group" data-toggle="buttons">
 154   <label class="btn btn-primary active">
 155     <input type="checkbox" checked autocomplete="off"> Checkbox 1 (pre-checked)
 156   </label>
 157   <label class="btn btn-primary">
 158     <input type="checkbox" autocomplete="off"> Checkbox 2
 159   </label>
 160   <label class="btn btn-primary">
 161     <input type="checkbox" autocomplete="off"> Checkbox 3
 162   </label>
 163 </div>
 164 {% endexample %}
 165
 166 {% example html %}
 167 <div class="btn-group" data-toggle="buttons">
 168   <label class="btn btn-primary active">
 169     <input type="radio" name="options" id="option1" autocomplete="off" checked> Radio 1 (preselected)
 170   </label>
 171   <label class="btn btn-primary">
 172     <input type="radio" name="options" id="option2" autocomplete="off"> Radio 2
 173   </label>
 174   <label class="btn btn-primary">
 175     <input type="radio" name="options" id="option3" autocomplete="off"> Radio 3
 176   </label>
 177 </div>
 178 {% endexample %}
 179
 180 ### Methods
 181
 182 | Method | Description |
 183 | --- | --- |
 184 | `$().button('toggle')` |Toggles push state. Gives the button the appearance that it has been activated.  |