0
# Button Components
1
2
Comprehensive button system with multiple variants optimized for different contexts and user actions, from simple clicks to complex dropdown menus.
3
4
## Capabilities
5
6
### Button Variants
7
8
Collection of specialized button components designed for specific use cases and contexts.
9
10
```typescript { .api }
11
/**
12
* Primary action button with emphasized styling
13
*/
14
function PrimaryButton(props: IButtonProps): JSX.Element;
15
16
/**
17
* Standard button with default styling
18
*/
19
function DefaultButton(props: IButtonProps): JSX.Element;
20
21
/**
22
* Command-style button without background, suitable for toolbars
23
*/
24
function ActionButton(props: IButtonProps): JSX.Element;
25
26
/**
27
* Button optimized for command bars with proper spacing and styling
28
*/
29
function CommandBarButton(props: IButtonProps): JSX.Element;
30
31
/**
32
* Button displaying only an icon, no text
33
*/
34
function IconButton(props: IButtonProps): JSX.Element;
35
36
/**
37
* Button with primary and secondary text areas
38
*/
39
function CompoundButton(props: IButtonProps): JSX.Element;
40
41
/**
42
* Button styled for message bars with appropriate contrast
43
*/
44
function MessageBarButton(props: IButtonProps): JSX.Element;
45
46
/**
47
* Button with dropdown menu functionality
48
*/
49
function SplitButton(props: IButtonProps): JSX.Element;
50
51
interface IButton {
52
/** Set focus to the button */
53
focus(): void;
54
/** Dismiss any open menu */
55
dismissMenu(): void;
56
/** Open the button's menu with optional focus settings */
57
openMenu(shouldFocusOnContainer?: boolean, shouldFocusOnMount?: boolean): void;
58
}
59
60
interface IButtonProps extends React.AllHTMLAttributes<HTMLAnchorElement | HTMLButtonElement | HTMLDivElement | BaseButton | Button> {
61
/** Reference to access component methods */
62
componentRef?: IRefObject<IButton>;
63
/** If provided, this component will be rendered as an anchor */
64
href?: string;
65
/** Changes the visual presentation of the button to be emphasized */
66
primary?: boolean;
67
/** Unique id to identify the item. Typically a duplicate of key value */
68
uniqueId?: string | number;
69
/** Whether the button is disabled */
70
disabled?: boolean;
71
/** Whether the button can have focus in disabled mode */
72
allowDisabledFocus?: boolean;
73
/** If set to true and if this is a splitButton (split == true) then the primary action of a split button is disabled */
74
primaryDisabled?: boolean;
75
/** Custom styling for individual elements within the button DOM */
76
styles?: IButtonStyles;
77
/** Theme provided by HOC */
78
theme?: ITheme;
79
/** Whether the button is checked */
80
checked?: boolean;
81
/** Whether button is a toggle button with distinct on and off states */
82
toggle?: boolean;
83
/** If provided, additional class name to provide on the root element */
84
className?: string;
85
/** The aria label of the button for the benefit of screen readers */
86
ariaLabel?: string;
87
/** Detailed description of the button for the benefit of screen readers */
88
ariaDescription?: string;
89
/** If provided and is true it adds an 'aria-hidden' attribute instructing screen readers to ignore the element */
90
ariaHidden?: boolean;
91
/** Text to render button label. If text is supplied, it will override any string in button children */
92
text?: string;
93
/** The props for the icon shown in the button */
94
iconProps?: IIconProps;
95
/** Props for button menu. Providing this will default to showing the menu icon */
96
menuProps?: IContextualMenuProps;
97
/** Callback that runs after Button's contextualmenu was closed (removed from the DOM) */
98
onAfterMenuDismiss?: () => void;
99
/** If set to true, and if menuProps and onClick are provided, the button will render as a SplitButton */
100
split?: boolean;
101
/** The props for the icon shown when providing a menu dropdown */
102
menuIconProps?: IIconProps;
103
/** Accessible label for the dropdown chevron button if this button is split */
104
splitButtonAriaLabel?: string;
105
/** Optional callback when menu is clicked */
106
onMenuClick?: (ev?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, button?: IButtonProps) => void;
107
/** Custom render function for the icon */
108
onRenderIcon?: IRenderFunction<IButtonProps>;
109
/** Custom render function for the label text */
110
onRenderText?: IRenderFunction<IButtonProps>;
111
/** Custom render function for the desciption text */
112
onRenderDescription?: IRenderFunction<IButtonProps>;
113
/** Custom render function for the aria description element */
114
onRenderAriaDescription?: IRenderFunction<IButtonProps>;
115
/** Custom render function for rendering the button children */
116
onRenderChildren?: IRenderFunction<IButtonProps>;
117
/** Custom render function for button menu icon */
118
onRenderMenuIcon?: IRenderFunction<IButtonProps>;
119
/** Deprecated at v6.3.2, to be removed at >= v7.0.0. Use menuAs instead */
120
onRenderMenu?: IRenderFunction<IContextualMenuProps>;
121
/** Render a custom menu in place of the normal one */
122
menuAs?: IComponentAs<IContextualMenuProps>;
123
/** Description of the action this button takes. Only used for compound buttons */
124
secondaryText?: string;
125
/** Deprecated at v1.2.3, to be removed at >= v2.0.0. Use specific button component instead */
126
buttonType?: ButtonType;
127
/** Deprecated at v0.56.2, to be removed at >= v1.0.0. Just pass in button props instead */
128
rootProps?: React.ButtonHTMLAttributes<HTMLButtonElement> | React.AnchorHTMLAttributes<HTMLAnchorElement>;
129
/** Any custom data the developer wishes to associate with the menu item. Deprecated, use checked if setting state */
130
toggled?: boolean;
131
/** Any custom data the developer wishes to associate with the menu item */
132
data?: any;
133
/** Method to provide the classnames to style a button */
134
getClassNames?: (
135
theme: ITheme,
136
className: string,
137
variantClassName: string,
138
iconClassName: string | undefined,
139
menuIconClassName: string | undefined,
140
disabled: boolean,
141
checked: boolean,
142
expanded: boolean,
143
isSplit: boolean | undefined,
144
allowDisabledFocus: boolean
145
) => IButtonClassNames;
146
/** Method to provide the classnames to style a button */
147
getSplitButtonClassNames?: (
148
disabled: boolean,
149
expanded: boolean,
150
checked: boolean,
151
allowDisabledFocus: boolean
152
) => ISplitButtonClassNames;
153
/** Provides a custom KeyCode that can be used to open the button menu */
154
menuTriggerKeyCode?: KeyCodes | null;
155
/** Optional keytip for this button */
156
keytipProps?: IKeytipProps;
157
/** Menu will not be created or destroyed when opened or closed, instead it will be hidden */
158
persistMenu?: boolean;
159
/** Style for the description text if applicable (for compound buttons.) Deprecated, use secondaryText instead */
160
description?: IStyle;
161
}
162
163
enum ButtonType {
164
normal = 0,
165
primary = 1,
166
hero = 2,
167
compound = 3,
168
command = 4,
169
icon = 5,
170
default = 6
171
}
172
173
enum ElementType {
174
button = 0,
175
anchor = 1
176
}
177
```
178
179
**Usage Examples:**
180
181
```typescript
182
import React, { useState } from "react";
183
import {
184
PrimaryButton,
185
DefaultButton,
186
ActionButton,
187
IconButton,
188
CompoundButton,
189
SplitButton,
190
IContextualMenuProps
191
} from "office-ui-fabric-react";
192
193
function BasicButtons() {
194
const handleClick = () => {
195
console.log("Button clicked!");
196
};
197
198
return (
199
<div>
200
<PrimaryButton
201
text="Primary Action"
202
onClick={handleClick}
203
/>
204
205
<DefaultButton
206
text="Secondary Action"
207
onClick={handleClick}
208
style={{ marginLeft: 8 }}
209
/>
210
211
<ActionButton
212
text="Action Button"
213
iconProps={{ iconName: "Add" }}
214
onClick={handleClick}
215
/>
216
</div>
217
);
218
}
219
220
function IconButtons() {
221
return (
222
<div>
223
<IconButton
224
iconProps={{ iconName: "Edit" }}
225
title="Edit"
226
ariaLabel="Edit item"
227
/>
228
229
<IconButton
230
iconProps={{ iconName: "Delete" }}
231
title="Delete"
232
ariaLabel="Delete item"
233
/>
234
235
<IconButton
236
iconProps={{ iconName: "More" }}
237
title="More actions"
238
ariaLabel="More actions"
239
/>
240
</div>
241
);
242
}
243
244
function CompoundButtons() {
245
return (
246
<div>
247
<CompoundButton
248
text="Create Document"
249
secondaryText="Start with a blank document"
250
iconProps={{ iconName: "Add" }}
251
onClick={() => console.log("Creating document")}
252
/>
253
254
<CompoundButton
255
text="Upload File"
256
secondaryText="Choose from your computer"
257
iconProps={{ iconName: "Upload" }}
258
onClick={() => console.log("Uploading file")}
259
/>
260
</div>
261
);
262
}
263
264
function MenuButtons() {
265
const menuProps: IContextualMenuProps = {
266
items: [
267
{
268
key: "save",
269
text: "Save",
270
iconProps: { iconName: "Save" },
271
onClick: () => console.log("Save clicked")
272
},
273
{
274
key: "saveAs",
275
text: "Save As...",
276
iconProps: { iconName: "SaveAs" },
277
onClick: () => console.log("Save As clicked")
278
},
279
{
280
key: "divider1",
281
itemType: ContextualMenuItemType.Divider
282
},
283
{
284
key: "export",
285
text: "Export",
286
iconProps: { iconName: "Download" },
287
subMenuProps: {
288
items: [
289
{
290
key: "pdf",
291
text: "Export as PDF",
292
onClick: () => console.log("Export PDF")
293
},
294
{
295
key: "word",
296
text: "Export as Word",
297
onClick: () => console.log("Export Word")
298
}
299
]
300
}
301
}
302
]
303
};
304
305
return (
306
<div>
307
<DefaultButton
308
text="File Actions"
309
iconProps={{ iconName: "ChevronDown" }}
310
menuProps={menuProps}
311
/>
312
313
<SplitButton
314
text="Save"
315
onClick={() => console.log("Quick save")}
316
menuProps={{
317
items: [
318
{
319
key: "save",
320
text: "Save",
321
onClick: () => console.log("Save")
322
},
323
{
324
key: "saveAs",
325
text: "Save As...",
326
onClick: () => console.log("Save As")
327
}
328
]
329
}}
330
/>
331
</div>
332
);
333
}
334
335
function DisabledButtons() {
336
return (
337
<div>
338
<PrimaryButton
339
text="Disabled Primary"
340
disabled={true}
341
/>
342
343
<DefaultButton
344
text="Disabled with Focus"
345
disabled={true}
346
allowDisabledFocus={true}
347
title="This button is disabled but can receive focus"
348
/>
349
</div>
350
);
351
}
352
```
353
354
### Base Button
355
356
Base component providing common functionality for all button variants. Generally not used directly.
357
358
```typescript { .api }
359
/**
360
* Base button component providing common functionality
361
* Generally not used directly - use specific button variants instead
362
*/
363
class BaseButton extends React.Component<IButtonProps, IButtonState> {
364
/** Set focus to the button */
365
focus(): void;
366
/** Dismiss any open menu */
367
dismissMenu(): void;
368
/** Open the button's menu with optional focus settings */
369
openMenu(shouldFocusOnContainer?: boolean, shouldFocusOnMount?: boolean): void;
370
}
371
372
interface IButtonState {
373
menuProps?: IContextualMenuProps;
374
}
375
```
376
377
### Button Styling
378
379
Comprehensive styling interface for customizing button appearance across all states and variants.
380
381
```typescript { .api }
382
interface IButtonStyles {
383
/** Root button element styles */
384
root?: IStyle;
385
/** Root element when button is hovered */
386
rootHovered?: IStyle;
387
/** Root element when button is pressed */
388
rootPressed?: IStyle;
389
/** Root element when button is checked */
390
rootChecked?: IStyle;
391
/** Root element when button is checked and hovered */
392
rootCheckedHovered?: IStyle;
393
/** Root element when button is checked and pressed */
394
rootCheckedPressed?: IStyle;
395
/** Root element when button is disabled */
396
rootDisabled?: IStyle;
397
/** Root element when button has focus */
398
rootFocused?: IStyle;
399
/** Flex container holding button contents */
400
flexContainer?: IStyle;
401
/** Text portion of the button */
402
textContainer?: IStyle;
403
/** Icon portion of the button */
404
icon?: IStyle;
405
/** Icon when button is hovered */
406
iconHovered?: IStyle;
407
/** Icon when button is pressed */
408
iconPressed?: IStyle;
409
/** Icon when button is checked */
410
iconChecked?: IStyle;
411
/** Icon when button is disabled */
412
iconDisabled?: IStyle;
413
/** Primary text label */
414
label?: IStyle;
415
/** Secondary text (for compound buttons) */
416
secondaryText?: IStyle;
417
/** Description text (for compound buttons) */
418
description?: IStyle;
419
/** Menu icon styles */
420
menuIcon?: IStyle;
421
/** Menu icon when hovered */
422
menuIconHovered?: IStyle;
423
/** Menu icon when pressed */
424
menuIconPressed?: IStyle;
425
/** Menu icon when button is checked */
426
menuIconChecked?: IStyle;
427
/** Menu icon when disabled */
428
menuIconDisabled?: IStyle;
429
/** Split button divider */
430
splitButtonDivider?: IStyle;
431
/** Split button menu button */
432
splitButtonMenuButton?: IStyle;
433
/** Split button menu button when hovered */
434
splitButtonMenuButtonHovered?: IStyle;
435
/** Split button menu button when pressed */
436
splitButtonMenuButtonPressed?: IStyle;
437
/** Split button menu button when checked */
438
splitButtonMenuButtonChecked?: IStyle;
439
/** Split button menu button when disabled */
440
splitButtonMenuButtonDisabled?: IStyle;
441
/** Split button menu icon */
442
splitButtonMenuIcon?: IStyle;
443
/** Split button menu icon when disabled */
444
splitButtonMenuIconDisabled?: IStyle;
445
/** Screen reader text */
446
screenReaderText?: IStyle;
447
}
448
449
interface IButtonStyleProps {
450
/** Theme provided by higher-order component */
451
theme: ITheme;
452
/** Additional CSS class */
453
className?: string;
454
/** Whether the button has focus */
455
focused?: boolean;
456
/** Whether the button is checked */
457
checked?: boolean;
458
/** Whether the button is disabled */
459
disabled?: boolean;
460
/** Whether the button has a menu */
461
hasMenu?: boolean;
462
/** Whether this is a split button */
463
split?: boolean;
464
/** Whether the button is primary styled */
465
primary?: boolean;
466
}
467
```
468
469
## Types
470
471
```typescript { .api }
472
// Contextual menu interfaces for button menus
473
interface IContextualMenuProps {
474
/** Array of menu items */
475
items: IContextualMenuItem[];
476
/** Target element for menu positioning */
477
target?: Element | string | MouseEvent | Point;
478
/** Whether the menu should be positioned above the target */
479
directionalHint?: DirectionalHint;
480
/** Additional CSS class */
481
className?: string;
482
/** Whether to use target width for menu width */
483
useTargetWidth?: boolean;
484
/** Whether the menu covers the target */
485
coverTarget?: boolean;
486
/** Gap between target and menu */
487
gapSpace?: number;
488
/** Beak width for callout */
489
beakWidth?: number;
490
/** Minimum width for the menu */
491
minWidth?: number;
492
/** Maximum width for the menu */
493
maxWidth?: number;
494
/** Whether to focus on menu open */
495
shouldFocusOnMount?: boolean;
496
/** Whether to focus on container */
497
shouldFocusOnContainer?: boolean;
498
/** Callback fired when menu is dismissed */
499
onDismiss?: (ev?: any, dismissAll?: boolean) => void;
500
/** Callback fired when item is clicked */
501
onItemClick?: (ev?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, item?: IContextualMenuItem) => boolean | void;
502
/** Custom render function for menu list */
503
onRenderMenuList?: IRenderFunction<IContextualMenuListProps>;
504
/** Properties for the callout */
505
calloutProps?: ICalloutProps;
506
/** Title for the menu */
507
title?: string;
508
/** ID for the menu */
509
id?: string;
510
/** ARIA label */
511
ariaLabel?: string;
512
/** Whether to hide scroll bars */
513
hidden?: boolean;
514
}
515
516
interface IContextualMenuItem {
517
/** Unique key for the item */
518
key: string;
519
/** Display text */
520
text?: string;
521
/** Item type (normal, divider, header, section) */
522
itemType?: ContextualMenuItemType;
523
/** Icon properties */
524
iconProps?: IIconProps;
525
/** Submenu properties */
526
subMenuProps?: IContextualMenuProps;
527
/** Whether the item is disabled */
528
disabled?: boolean;
529
/** Whether the item is checked */
530
checked?: boolean;
531
/** Whether the item can be checked */
532
canCheck?: boolean;
533
/** Whether the item is split into primary and secondary actions */
534
split?: boolean;
535
/** Data associated with the item */
536
data?: any;
537
/** Callback fired when item is clicked */
538
onClick?: (ev?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, item?: IContextualMenuItem) => boolean | void;
539
/** Custom render function for the item */
540
onRender?: (item: IContextualMenuItem, dismissMenu: (ev?: any, dismissAll?: boolean) => void) => React.ReactNode;
541
/** ARIA label */
542
ariaLabel?: string;
543
/** Title attribute */
544
title?: string;
545
/** Section properties for section items */
546
sectionProps?: IContextualMenuSection;
547
/** Additional CSS class */
548
className?: string;
549
/** Custom styles */
550
style?: React.CSSProperties;
551
/** Role attribute */
552
role?: string;
553
/** Primary disabled state (for split items) */
554
primaryDisabled?: boolean;
555
/** Short name for the item */
556
shortName?: string;
557
}
558
559
enum ContextualMenuItemType {
560
Normal = 0,
561
Divider = 1,
562
Header = 2,
563
Section = 3
564
}
565
566
// Key codes for keyboard interactions
567
enum KeyCodes {
568
enter = 13,
569
space = 32,
570
escape = 27,
571
tab = 9,
572
up = 38,
573
down = 40,
574
left = 37,
575
right = 39
576
}
577
```