You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: packages/documentation-site/patternfly-docs/content/design-guidelines/components/button/button.md
+85-38
Original file line number
Diff line number
Diff line change
@@ -3,18 +3,26 @@ id: Button
3
3
section: components
4
4
---
5
5
6
+
import '../components.css';
7
+
6
8
## Usage
9
+
7
10
There are certain cases where specific buttons must be used within your UI.
8
11
9
12
Follow these guidelines for buttons in wizards (shown in the image below):
13
+
10
14
* The **Next** button should always be a [primary button](#primary-button).
11
15
* The **Back** button should always be a [secondary button](#secondary-button).
12
16
* The **Cancel** button should always be a [link button](#link-button).
13
17
14
-
<imgsrc="./img/wizard.png"alt="Example of buttons in a wizard"/>
18
+
<divclass="ws-docs-content-img">
19
+
<img src="./img/wizard.png" alt="Example of buttons in a wizard"/>
20
+
</div>
15
21
16
22
## Variations
23
+
17
24
The following button styles, shown in order of visual hierarchy, can be used in your designs according to your needs.
25
+
18
26
*[Danger button](#danger-button)
19
27
*[Primary button](#primary-button)
20
28
*[Secondary button](#secondary-button)
@@ -24,7 +32,9 @@ The following button styles, shown in order of visual hierarchy, can be used in
24
32
*[Call To Action button](#call-to-action-button)
25
33
*[Progress button](#progress-button)
26
34
27
-
<imgsrc="./img/buttons.png"alt="Images of all button types"width="607"/>
35
+
<divclass="ws-docs-content-img">
36
+
<img src="./img/buttons.png" alt="Images of all button types" width="607"/>
37
+
</div>
28
38
29
39
You don't need to use these buttons in the order that their labels imply. For example, you don't always need to use the secondary button as the second button in your designs. The most important thing is to establish a visual hierarchy between any buttons in your designs. There are, however, some best practices to keep in mind.
30
40
@@ -34,27 +44,35 @@ Danger buttons are the most prominent of all the button options. Use danger butt
34
44
35
45
_Example of a danger button in a modal_
36
46
37
-
<imgsrc="./img/danger.png"alt="Example of danger button used in a modal"width="521"/>
47
+
<divclass="ws-docs-content-img">
48
+
<img src="./img/danger.png" alt="Example of danger button used in a modal" width="521"/>
49
+
</div>
38
50
39
51
### Primary button ###
40
52
41
53
A primary button is the most prominent button on a page, used for the most important call to action on a page. Try to limit primary buttons to one per page.
42
54
43
55
_Example of a primary button inside a toolbar_
44
56
45
-
<imgsrc="./img/prim_ex_1.png"alt="Example of a primary button inside a toolbar"width="1159"/>
57
+
<divclass="ws-docs-content-img">
58
+
<img src="./img/prim_ex_1.png" alt="Example of a primary button inside a toolbar" width="1159"/>
59
+
</div>
46
60
47
61
_Example of a primary button inside an empty state_
48
62
49
-
<imgsrc="./img/prim_ex_2.png"alt="Example of a primary button inside an empty state"width="656"/>
63
+
<divclass="ws-docs-content-img">
64
+
<img src="./img/prim_ex_2.png" alt="Example of a primary button inside an empty state" width="656"/>
65
+
</div>
50
66
51
67
### Secondary button ###
52
68
53
69
Secondary buttons are buttons with less visual prominence than primary buttons. Use secondary buttons for general actions on a page, that don’t require as much emphasis as primary button actions. For example, you can use secondary buttons where there are multiple actions, like in toolbars or data lists.
54
70
55
71
_Example of secondary buttons in data lists_
56
72
57
-
<imgsrc="./img/sec_ex.png"alt="Example of secondary buttons in data lists" />
73
+
<divclass="ws-docs-content-img">
74
+
<img src="./img/sec_ex.png" alt="Example of secondary buttons in data lists" />
75
+
</div>
58
76
59
77
### Tertiary button ###
60
78
@@ -64,70 +82,89 @@ In this example, you can see a tertiary button used to show a possible “Edit
64
82
65
83
_Example of tertiary button on a page_
66
84
67
-
<imgsrc="./img/tert_edit.png"alt="Example of tertiary button on a page"width="1500" />
85
+
<divclass="ws-docs-content-img">
86
+
<img src="./img/tert_edit.png" alt="Example of tertiary button on a page" width="1500" />
87
+
</div>
68
88
69
89
### Link button ###
70
90
71
91
Links buttons are labeled buttons with no background or border. Link buttons can be used for actions that:
92
+
72
93
* May not need as much emphasis.
73
94
* Navigate users to another page within the same window.
74
95
* Navigate users to an external page.
75
96
76
97
While all link buttons lack borders, they can still vary in appearance. Link buttons that navigate users to another page within the same window should be presented as stand-alone text. Link buttons that navigate users to an external page may include an icon on the left or right of the text to further emphasize the action. For example, you could add an external link icon to show that clicking on it will navigate users externally to another website or application.
77
98
78
-
<imgsrc="./img/link-left.png"alt="Example of link button with icon on the left"width="143"/>
79
-
80
-
<imgsrc="./img/link-right.png"alt="Example of link button with icon on the right"width="143"/>
99
+
<divclass="ws-docs-content-img">
100
+
<img src="./img/external_links.png" alt="Example of link button with icon on the left and the right" width="218"/>
101
+
</div>
81
102
82
103
You might use a link button instead of a secondary button format to create greater visual hierarchy between two buttons. Examples include using text buttons as cancel buttons in modals or wizards, as well as for secondary actions in empty states.
83
104
84
105
_Example of a link button in a modal_
85
106
86
-
<imgsrc="./img/link_modal.png"alt="Example of a link button in a modal"width="446"/>
107
+
<divclass="ws-docs-content-img">
108
+
<img src="./img/link_modal.png" alt="Example of a link button in a modal" width="446"/>
109
+
</div>
87
110
88
111
_Example of link buttons in an empty state_
89
112
90
-
<imgsrc="./img/empty_state_links.png"alt="Example of link buttons in an empty state"width="640"/>
113
+
<divclass="ws-docs-content-img">
114
+
<img src="./img/empty_state_links.png" alt="Example of link buttons in an empty state" width="640"/>
115
+
</div>
91
116
92
-
### When to use
117
+
### When to use
93
118
94
119
Always use link buttons in the following cases:
95
120
96
121
* For cancel buttons in wizards or modals
97
122
123
+
<divclass="ws-docs-content-img">
98
124
<img src="./img/link_modal.png" alt="Example of link button used in modal" width="446"/>
125
+
</div>
99
126
100
127
* For more actions in empty states
101
128
129
+
<divclass="ws-docs-content-img">
102
130
<img src="./img/link_empty.png" alt="Example of a link button in an empty state" width="600"/>
131
+
</div>
103
132
104
133
* For action buttons in tables
105
134
135
+
<divclass="ws-docs-content-img">
106
136
<img src="./img/link_table.png" alt="Example of link buttons in a table"/>
137
+
</div>
107
138
108
139
* For action buttons in alerts
109
140
141
+
<divclass="ws-docs-content-img">
110
142
<img src="./img/link_alert.png" alt="Example of link button in an alert" width="309"/>
143
+
</div>
111
144
112
145
### Icon button ###
113
146
114
147
Icon buttons are useful in places where space is limited. For example, if you have too many actions within a menu, you could use a kebab icon to indicate more actions, or an export icon for exporting data. You can also use this button type for actions that are commonly associated with icons, like an exit icon to close a window or a hamburger icon to open a menu.
115
148
116
149
For example, this toolbar uses a kebab icon as an action button due to limited space.
117
150
118
-
<imgsrc="./img/icon_button.png"alt="Example of kebab used as an icon button inside a toolbar"width="1159"/>
151
+
<divclass="ws-docs-content-img">
152
+
<img src="./img/icon_button.png" alt="Example of kebab used as an icon button inside a toolbar" width="1159"/>
153
+
</div>
119
154
120
155
### Call To Action button ###
121
156
122
157
Call To Action (CTA) buttons and links are used on websites to direct users to complete an action. For example, a product detail page could include a CTA button labeled 'Try it now,' which would guide users to a purchase page.
123
158
124
-
<imgsrc="./img/CTAs.png"alt="Images of all CTA types"width="708"/>
159
+
<divclass="ws-docs-content-img">
160
+
<img src="./img/CTAs.png" alt="Images of all CTA types" width="708"/>
161
+
</div>
125
162
126
163
Call To Actions have similar variants to regular buttons (although they have a larger padding), and follow the same visual hierarchy. However, CTA buttons are used only to indicate a desired next step, whereas other button types may also be used to link to additional information or actions. Call To Actions should be used sparingly (ideally one per page, or a primary and secondary CTA).
127
164
128
165
### Progress button ###
129
166
130
-
A progress button can be used to provide the user with feedback that an action is in progress after the button is clicked. To indicate that an action is taking place, a spinner is inserted in front of the button label.
167
+
A progress button can be used to provide the user with feedback that an action is in progress after the button is clicked. To indicate that an action is taking place, a spinner is inserted in front of the button label.
131
168
132
169
**When to use a progress button**
133
170
@@ -139,7 +176,9 @@ Do not use a progress button for operations that will take more than a few secon
139
176
140
177
_Example of using a progress button to test a repository before final configuration_
141
178
142
-
<imgsrc="./img/progress_bar_stages.png"alt="Example of progress button usage"width="1828"/>
179
+
<divclass="ws-docs-content-img">
180
+
<img src="./img/progress_bar_stages.png" alt="Example of progress button usage" width="1828"/>
181
+
</div>
143
182
144
183
1. The user clicks “try sample repository".
145
184
@@ -171,69 +210,77 @@ The placement of buttons on wizards will depend on the layout of content you pre
171
210
172
211
### Button spacing and action lists
173
212
174
-
The standard spacing between each button is 16px, even for danger buttons. If buttons are stacked vertically, the spacing between each button should be 8px.
213
+
The standard spacing between each button is `--pf-t--global--spacer--md` (16px), even for danger buttons. If buttons are stacked vertically, the spacing between each button should be `--pf-t--global--spacer--sm` (8px).
175
214
176
215
_Standard spacing_
177
216
178
-
<imgsrc="./img/button_16px.png"alt="Standard button spacing with spacers"width="214"/>
217
+
<divclass="ws-docs-content-img">
218
+
<img src="./img/button_16px.png" alt="Standard button spacing with spacers" width="214"/>
219
+
</div>
179
220
180
221
_Stacked spacing_
181
222
182
-
<imgsrc="./img/button_stacked.png"alt="Stacked button spacing with spacers"width="222"/>
223
+
<divclass="ws-docs-content-img">
224
+
<img src="./img/button_stacked.png" alt="Stacked button spacing with spacers" width="222"/>
225
+
</div>
183
226
184
227
### Exceptions ###
185
228
186
229
Exceptions to the standard spacing guidelines are as follows:
187
230
188
231
#### Wizards ####
189
232
190
-
In wizards, the **Cancel** button is spaced 48px away from the primary and secondary **Next** and **Back** buttons, and 24px away if stacked.
233
+
In wizards, the **Cancel** button is spaced `--pf-t--global--spacer--2xl` (48px) away from the primary and secondary **Next** and **Back** buttons, and `--pf-t--global--spacer--lg` (24px) away if stacked.
191
234
192
235
_Wizard spacing_
193
236
194
-
<imgsrc="./img/button_wizard.png"alt="Wizard button spacing with spacers"width="304"/>
195
-
237
+
<divclass="ws-docs-content-img">
238
+
<img src="./img/button_wizard.png" alt="Wizard button spacing with spacers" width="304"/>
239
+
</div>
196
240
_Wizard stacked spacing_
197
241
198
-
<imgsrc="./img/button_wizard_stacked.png"alt="Stacked wizard button spacing with spacers"width="121"/>
199
-
200
-
#### Modals ####
201
-
202
-
In modals, the primary button is spaced only 8px away from the secondary button, rather than the standard 16px.
203
-
204
-
_Modal spacing_
205
-
206
-
<imgsrc="./img/modal_exception.png"alt="Modal button spacing with spacers"width="446"/>
242
+
<divclass="ws-docs-content-img">
243
+
<img src="./img/button_wizard_stacked.png" alt="Stacked wizard button spacing with spacers" width="360"/>
244
+
</div>
207
245
208
246
#### Toolbars ####
209
247
210
-
Button spacing in toolbars depends on the button type. Normal 16px spacing applies between primary and secondary buttons. However, there should only be 8px between icon buttons.
248
+
Button spacing in toolbars depends on the button type and how they are grouped. For example, groups of primary and secondary buttons use `--pf-t--global--spacer--sm` (8px) spacing between buttons and `--pf-t--global--spacer--md` (16px) between groups. Icon buttons inside a grouping use `--pf-t--global--spacer--xs` (4px) spacing and `--pf-t--global--spacer--md` (16px) between groups.
211
249
212
250
_Toolbar spacing_
213
251
214
-
<imgsrc="./img/toolbar_exception.png"alt="Toolbar button spacing with spacers"width="312"/>
252
+
<divclass="ws-docs-content-img">
253
+
<img src="./img/toolbar_exception.png" alt="Toolbar button spacing with spacers" width="312"/>
254
+
</div>
215
255
216
256
If you have a specific use case where buttons need to be spaced further away from the rest, the button groups action list allows for customization as needed.
217
257
218
258
_Action group spacing_
219
259
220
-
<imgsrc="./img/button_action_group.png"alt="Action group spacing with spacers"width="416"/>
260
+
<divclass="ws-docs-content-img">
261
+
<img src="./img/button_action_group.png" alt="Action group spacing with spacers" width="416"/>
262
+
</div>
221
263
222
264
### Buttons and overflow menus
223
265
224
266
There are cases where you will have multiple buttons next to each other, like in a toolbar. When the space shrinks (e.g., switching from desktop to mobile view), you can have the buttons collapse into a kebab overflow menu. Additionally, you can choose to make the primary action persist or have all options collapse into the kebab.
225
267
226
268
_Buttons appear in the toolbar_
227
269
228
-
<imgsrc="./img/overflow_1.png"alt="Pre-over flow menu in toolbar, where all actions appear in the toolbar itself"width="1191"/>
270
+
<divclass="ws-docs-content-img">
271
+
<img src="./img/overflow_1.png" alt="Pre-over flow menu in toolbar, where all actions appear in the toolbar itself" width="1191"/>
272
+
</div>
229
273
230
274
_Buttons placed in overflow menu due to limited space, with primary button persisting_
231
275
232
-
<imgsrc="./img/overflow_2.png"alt="Post-overflow menu in toolbar, where toolbar has become smaller in width, prompting an overflow menu for secondary actions, while primary button persists in the toolbar itself"width="1010"/>
276
+
<divclass="ws-docs-content-img">
277
+
<img src="./img/overflow_2.png" alt="Post-overflow menu in toolbar, where toolbar has become smaller in width, prompting an overflow menu for secondary actions, while primary button persists in the toolbar itself" width="1010"/>
278
+
</div>
233
279
234
280
## Placement
235
281
236
282
Buttons in forms, modals, or wizards should always be left aligned in the box. This solves for:
283
+
237
284
***Modularity and flexibility:** A standard alignment creates consistency in how objects appear across all areas of an app.
238
285
***Accessibility:** The form submit buttons are on the same scan line as the form fields, which benefits users who are sight-limited. Also, users who are blind can more easily navigate left-aligned form submit buttons because the button order is consistent across all contexts.
239
286
***Responsiveness:** The most important actions (i.e., primary buttons) are encountered first when elements are stacked vertically.
@@ -257,6 +304,6 @@ When writing button labels:
257
304
258
305
Use specific, action-focused labels that match what the user will see when they arrive at their location. For example, if you are sending a user to a dashboard, your link label might read _View dashboard_. For a link directing a user to a support forum, the label might read _Get help in the support forum_. See [PatternFly's content guidelines](/ux-writing/about-ux-writing) for additional guidance.
259
306
260
-
## Accessibility
307
+
## Accessibility
261
308
262
309
For information regarding accessibility, visit the [button accessibility page](/components/button/accessibility).
0 commit comments