]>
Commit | Line | Data |
---|---|---|
91e44d91 S |
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. | |