| commit | author | age | ||
| 83c3f6 | 1 | --- |
| SP | 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: "/docs/4.2/components/" | |
| 7 | toc: true | |
| 8 | --- | |
| 9 | ||
| 10 | ## Examples | |
| 11 | ||
| 12 | Bootstrap includes several predefined button styles, each serving its own semantic purpose, with a few extras thrown in for more control. | |
| 13 | ||
| 14 | {% capture example %} | |
| 15 | {% for color in site.data.theme-colors %} | |
| 16 | <button type="button" class="btn btn-{{ color.name }}">{{ color.name | capitalize }}</button>{% endfor %} | |
| 17 | ||
| 18 | <button type="button" class="btn btn-link">Link</button> | |
| 19 | {% endcapture %} | |
| 20 | {% include example.html content=example %} | |
| 21 | ||
| 22 | {% include callout-warning-color-assistive-technologies.md %} | |
| 23 | ||
| 24 | ## Button tags | |
| 25 | ||
| 26 | 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). | |
| 27 | ||
| 28 | 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. | |
| 29 | ||
| 30 | {% capture example %} | |
| 31 | <a class="btn btn-primary" href="#" role="button">Link</a> | |
| 32 | <button class="btn btn-primary" type="submit">Button</button> | |
| 33 | <input class="btn btn-primary" type="button" value="Input"> | |
| 34 | <input class="btn btn-primary" type="submit" value="Submit"> | |
| 35 | <input class="btn btn-primary" type="reset" value="Reset"> | |
| 36 | {% endcapture %} | |
| 37 | {% include example.html content=example %} | |
| 38 | ||
| 39 | ## Outline buttons | |
| 40 | ||
| 41 | 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. | |
| 42 | ||
| 43 | {% capture example %} | |
| 44 | {% for color in site.data.theme-colors %} | |
| 45 | <button type="button" class="btn btn-outline-{{ color.name }}">{{ color.name | capitalize }}</button>{% endfor %} | |
| 46 | {% endcapture %} | |
| 47 | {% include example.html content=example %} | |
| 48 | ||
| 49 | ## Sizes | |
| 50 | ||
| 51 | Fancy larger or smaller buttons? Add `.btn-lg` or `.btn-sm` for additional sizes. | |
| 52 | ||
| 53 | {% capture example %} | |
| 54 | <button type="button" class="btn btn-primary btn-lg">Large button</button> | |
| 55 | <button type="button" class="btn btn-secondary btn-lg">Large button</button> | |
| 56 | {% endcapture %} | |
| 57 | {% include example.html content=example %} | |
| 58 | ||
| 59 | {% capture example %} | |
| 60 | <button type="button" class="btn btn-primary btn-sm">Small button</button> | |
| 61 | <button type="button" class="btn btn-secondary btn-sm">Small button</button> | |
| 62 | {% endcapture %} | |
| 63 | {% include example.html content=example %} | |
| 64 | ||
| 65 | Create block level buttons—those that span the full width of a parent—by adding `.btn-block`. | |
| 66 | ||
| 67 | {% capture example %} | |
| 68 | <button type="button" class="btn btn-primary btn-lg btn-block">Block level button</button> | |
| 69 | <button type="button" class="btn btn-secondary btn-lg btn-block">Block level button</button> | |
| 70 | {% endcapture %} | |
| 71 | {% include example.html content=example %} | |
| 72 | ||
| 73 | ## Active state | |
| 74 | ||
| 75 | 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. | |
| 76 | ||
| 77 | {% capture example %} | |
| 78 | <a href="#" class="btn btn-primary btn-lg active" role="button" aria-pressed="true">Primary link</a> | |
| 79 | <a href="#" class="btn btn-secondary btn-lg active" role="button" aria-pressed="true">Link</a> | |
| 80 | {% endcapture %} | |
| 81 | {% include example.html content=example %} | |
| 82 | ||
| 83 | ## Disabled state | |
| 84 | ||
| 85 | Make buttons look inactive by adding the `disabled` boolean attribute to any `<button>` element. | |
| 86 | ||
| 87 | {% capture example %} | |
| 88 | <button type="button" class="btn btn-lg btn-primary" disabled>Primary button</button> | |
| 89 | <button type="button" class="btn btn-secondary btn-lg" disabled>Button</button> | |
| 90 | {% endcapture %} | |
| 91 | {% include example.html content=example %} | |
| 92 | ||
| 93 | Disabled buttons using the `<a>` element behave a bit different: | |
| 94 | ||
| 95 | - `<a>`s don't support the `disabled` attribute, so you must add the `.disabled` class to make it visually appear disabled. | |
| 96 | - 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. | |
| 97 | - Disabled buttons should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies. | |
| 98 | ||
| 99 | {% capture example %} | |
| 100 | <a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a> | |
| 101 | <a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a> | |
| 102 | {% endcapture %} | |
| 103 | {% include example.html content=example %} | |
| 104 | ||
| 105 | {% capture callout %} | |
| 106 | ##### Link functionality caveat | |
| 107 | ||
| 108 | 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. | |
| 109 | {% endcapture %} | |
| 110 | {% include callout.html content=callout type="warning" %} | |
| 111 | ||
| 112 | ## Button plugin | |
| 113 | ||
| 114 | Do more with buttons. Control button states or create groups of buttons for more components like toolbars. | |
| 115 | ||
| 116 | ### Toggle states | |
| 117 | ||
| 118 | 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>`. | |
| 119 | ||
| 120 | {% capture example %} | |
| 121 | <button type="button" class="btn btn-primary" data-toggle="button" aria-pressed="false" autocomplete="off"> | |
| 122 | Single toggle | |
| 123 | </button> | |
| 124 | {% endcapture %} | |
| 125 | {% include example.html content=example %} | |
| 126 | ||
| 127 | ### Checkbox and radio buttons | |
| 128 | ||
| 129 | 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 their toggling behavior via JavaScript and add `.btn-group-toggle` to style the `<input>`s within your buttons. **Note that you can create single input-powered buttons or groups of them.** | |
| 130 | ||
| 131 | 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. | |
| 132 | ||
| 133 | Note that pre-checked buttons require you to manually add the `.active` class to the input's `<label>`. | |
| 134 | ||
| 135 | {% capture example %} | |
| 136 | <div class="btn-group-toggle" data-toggle="buttons"> | |
| 137 | <label class="btn btn-secondary active"> | |
| 138 | <input type="checkbox" checked autocomplete="off"> Checked | |
| 139 | </label> | |
| 140 | </div> | |
| 141 | {% endcapture %} | |
| 142 | {% include example.html content=example %} | |
| 143 | ||
| 144 | {% capture example %} | |
| 145 | <div class="btn-group btn-group-toggle" data-toggle="buttons"> | |
| 146 | <label class="btn btn-secondary active"> | |
| 147 | <input type="radio" name="options" id="option1" autocomplete="off" checked> Active | |
| 148 | </label> | |
| 149 | <label class="btn btn-secondary"> | |
| 150 | <input type="radio" name="options" id="option2" autocomplete="off"> Radio | |
| 151 | </label> | |
| 152 | <label class="btn btn-secondary"> | |
| 153 | <input type="radio" name="options" id="option3" autocomplete="off"> Radio | |
| 154 | </label> | |
| 155 | </div> | |
| 156 | {% endcapture %} | |
| 157 | {% include example.html content=example %} | |
| 158 | ||
| 159 | ### Methods | |
| 160 | ||
| 161 | | Method | Description | | |
| 162 | | --- | --- | | |
| 163 | | `$().button('toggle')` | Toggles push state. Gives the button the appearance that it has been activated. | | |
| 164 | | `$().button('dispose')` | Destroys an element's button. | | |
