Button
A button is used to indicate one or more available actions for the user.
Examples
Basic buttons:
Icon and link buttons:
Usage
Do
- Use to open dialogs, and panels; toggle states; confirm actions
- Use when it can be disabled (e.g. a hyperlink to another page should never be disabled, whereas a form submit button can)
- Use sentence case for text inside buttons
- Start the button text with a clear action verb (e.g. “Save” instead of “OK”)
- Include a clarifying noun if there is any room for interpretation about what the verb operates on (e.g. “Discard changes”)
- Keep the text minimal to avoid wrapping
- Use danger buttons very sparingly for actions with serious and/or destructive consequences that may be difficult or impossible to reverse
- Avoid using more than one primary button per screen
- Avoid using split button — even though the two target areas of the split button have a large enough touch area on small screens, they are still more difficult to use than a menu button
Don’t
- Resize the buttons — except for the tree open/close icon button, there is only one button size
- Match button widths for buttons that are side by side
- Use the danger button style on menu button, split button, or button with label and value
- Use a split button before considering if you can reduce the number of actions available
- Use buttons to navigate to external pages
Anatomy
There are six button types:
- (1) Button: Triggers an immediate action
- (2) Button with icon: Triggers an immediate action
- (3) Menu button: Opens a dropdown with various options
- (4) Button with label and value
- (5) Icon button: Triggers an immediate action
- (6) Split button: Always has a primary immediate action, triggered on one side; and the option to open a dropdown with more options, trigger on the other side
There are four button styles:
- (1) Standard button
- (2) Primary button
- (3) Subtle button
- (4) Danger button
Alignment
Related
Developer guidance
If a button takes a user to a known href, specify this via the href prop to allow users to optionally open in a new tab or window, and not via an onClick handler.
APIs
IButton
focus
(): void
Sets focus to the Button.
IButtonProps
ariaChecked
boolean
Adds aria-checked to the button element.
ariaControls
string
Adds aria-controls to the button element.
NOTE: Give the base Id in this case, NOT the getSafeId.
ariaDescribedBy
string
Adds aria-describedby to the button element.
NOTE: Give the base Id in this case, NOT the getSafeId.
ariaDisabled
boolean
Adds aria-disabled to the button element.
ariaExpanded
boolean
Adds aria-expanded to the button element.
ariaHasPopup
boolean
Adds aria-haspopup to the button element.
ariaHidden
boolean
Adds aria-disabled to the button element.
ariaLabel
string
Adds aria-label to the button element.
ariaLabelledBy
string
Adds aria-labelledby to the button element.
ariaPosInSet
number
Adds aria-posinset to the button element.
ariaPressed
boolean
Adds aria-pressed to the button element.
ariaRoleDescription
string
Adds aria-roledescription to the button element.
ariaSelected
boolean
Adds aria-selected to the button element.
ariaSetSize
number
Adds aria-setsize to the button element.
autoFocusfalse
boolean
If true, the button is focused when mounted.
className
string
Optional class name to add to the button element.
danger
boolean
Set to true if this button should be styled with a danger color.
dataIndex
number
An optional data attribute to add to the button element.
disabled
boolean
If true, the button cannot be interacted with.
excludeFocusZone
boolean
Set to true if you don't want the button's focus managed by a FocusZone.
excludeTabStop
boolean
Set to true if you don't want the button's to be tabbable.
focusZoneId
string
Set the buttons focus zone to be different than the closest parent focus zone.
href
string
Href to navigate to when the button is clicked. Pass in if this is a link button.
id
string
A unique identifier for the button
onBlur
(event: React.FocusEvent<HTMLElement>) => void
Callback to handle blur events
onClick
(event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void
Callback to handle button clicks.
onFocus
(event: React.FocusEvent<HTMLElement>) => void
Callback to handle focus events
onKeyDown
(event: React.KeyboardEvent<HTMLElement>) => void
Callback to handle button key down.
onMouseDown
(event: React.MouseEvent<HTMLElement>) => void
Callback to handle mouse leave events.
onMouseLeave
(event: React.MouseEvent<HTMLElement>) => void
Callback to handle mouse leave events.
onMouseOver
(event: React.MouseEvent<HTMLElement> | React.MouseEvent<HTMLElement>) => void
Callback to handle mouse over events.
primary
boolean
Set to true if this button should be styled with a primary color.
rel
string
Optional, relationship between current document and the linked document. Only required if href is set.
rolebutton
string
Optional aria role.
style
React.CSSProperties
Extra styles that should be added to the element, this supports dynamic
styles that couldn't be defined statically in CSS.
subtle
boolean
Set to true to style this as a subtle button.
tabIndex
number
Sets the tabindex on the button element.
target
string
Optional,context in which the linked resource will open.
text
string
Optional text to render inside the button.
tooltipProps
Optional tooltip to show when the button is hovered.
For icon only buttons, the tooltip will default to the aria-label.
type"button" if href is not set, otherwise undefined
"submit" | "reset" | "button"
Optional, type of button.
IExpandableButtonProps
anchorElement
HTMLElement
Element the dropdown should open relative to, if the dropdown shouldn't
open relative to the button itself.
anchorOffset
IOffset
Offset from the anchor element or point for the dropdown.
anchorOrigin
IOrigin
Location on the anchor element the dropdown should be relative to.
anchorPoint
IPoint
anchorPoint can be supplied if the dropdown should open at a fixed
point instead of relative to the button.
ariaCheckedInherited From: IButtonProps
boolean
Adds aria-checked to the button element.
ariaControlsInherited From: IButtonProps
string
Adds aria-controls to the button element.
NOTE: Give the base Id in this case, NOT the getSafeId.
ariaDescribedByInherited From: IButtonProps
string
Adds aria-describedby to the button element.
NOTE: Give the base Id in this case, NOT the getSafeId.
ariaDisabledInherited From: IButtonProps
boolean
Adds aria-disabled to the button element.
ariaExpandedInherited From: IButtonProps
boolean
Adds aria-expanded to the button element.
ariaHasPopupInherited From: IButtonProps
boolean
Adds aria-haspopup to the button element.
ariaHiddenInherited From: IButtonProps
boolean
Adds aria-disabled to the button element.
ariaLabelInherited From: IButtonProps
string
Adds aria-label to the button element.
ariaLabelledByInherited From: IButtonProps
string
Adds aria-labelledby to the button element.
ariaPosInSetInherited From: IButtonProps
number
Adds aria-posinset to the button element.
ariaPressedInherited From: IButtonProps
boolean
Adds aria-pressed to the button element.
ariaRoleDescriptionInherited From: IButtonProps
string
Adds aria-roledescription to the button element.
ariaSelectedInherited From: IButtonProps
boolean
Adds aria-selected to the button element.
ariaSetSizeInherited From: IButtonProps
number
Adds aria-setsize to the button element.
autoFocusfalseInherited From: IButtonProps
boolean
If true, the button is focused when mounted.
buttonClassName
string
Optional className to apply to the button element
classNameInherited From: IButtonProps
string
Optional class name to add to the button element.
containerRef
React.RefObject<HTMLDivElement>
Ref to pass to the container element.
dangerInherited From: IButtonProps
boolean
Set to true if this button should be styled with a danger color.
dataIndexInherited From: IButtonProps
number
An optional data attribute to add to the button element.
disabledInherited From: IExpandableSharedProps
boolean
If true, the button cannot be interacted with.
dropdownId
string
Optional Id that should be used on the dropdown to uniquely identify
this element.
dropdownOrigin
IOrigin
Location on the dropdown to make relative to the button location.
excludeFocusZoneInherited From: IButtonProps
boolean
Set to true if you don't want the button's focus managed by a FocusZone.
excludeTabStopInherited From: IButtonProps
boolean
Set to true if you don't want the button's to be tabbable.
expandKeyKeyCode.DownArrowInherited From: IExpandableSharedProps
KeyCode | KeyCode[]
The key used to expand the components callout.
focusZoneIdInherited From: IButtonProps
string
Set the buttons focus zone to be different than the closest parent focus zone.
hideDropdownIcon
boolean
If hideDropdownIcon is supplied the button acts as a dropdown button
without showing the dropdown arrows.
hrefInherited From: IButtonProps
string
Href to navigate to when the button is clicked. Pass in if this is a link button.
iconPropsInherited From: IButtonProps
Object specifying which icon to display within the button.
idInherited From: IButtonProps
string
A unique identifier for the button
onBlurInherited From: IButtonProps
(event: React.FocusEvent<HTMLElement>) => void
Callback to handle blur events
onClickInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void
Callback to handle button clicks.
onCollapseInherited From: IExpandableSharedProps
() => void
Optional callback to call when the dropdown is collapsed.
onExpandInherited From: IExpandableSharedProps
() => void
Optional callback to call when the dropdown is expanded.
onFocusInherited From: IButtonProps
(event: React.FocusEvent<HTMLElement>) => void
Callback to handle focus events
onKeyDownInherited From: IButtonProps
(event: React.KeyboardEvent<HTMLElement>) => void
Callback to handle button key down.
onMouseDownInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement>) => void
Callback to handle mouse leave events.
onMouseLeaveInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement>) => void
Callback to handle mouse leave events.
onMouseOverInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement> | React.MouseEvent<HTMLElement>) => void
Callback to handle mouse over events.
primaryInherited From: IButtonProps
boolean
Set to true if this button should be styled with a primary color.
relInherited From: IButtonProps
string
Optional, relationship between current document and the linked document. Only required if href is set.
renderCalloutrequired
RenderCalloutFunction
Method used to create the callout.
rolebuttonInherited From: IButtonProps
string
Optional aria role.
styleInherited From: IButtonProps
React.CSSProperties
Extra styles that should be added to the element, this supports dynamic
styles that couldn't be defined statically in CSS.
subtleInherited From: IButtonProps
boolean
Set to true to style this as a subtle button.
tabIndexInherited From: IButtonProps
number
Sets the tabindex on the button element.
targetInherited From: IButtonProps
string
Optional,context in which the linked resource will open.
textInherited From: IButtonProps
string
Optional text to render inside the button.
tooltipPropsInherited From: IButtonProps
Optional tooltip to show when the button is hovered.
For icon only buttons, the tooltip will default to the aria-label.
type"button" if href is not set, otherwise undefinedInherited From: IButtonProps
"submit" | "reset" | "button"
Optional, type of button.
IMenuButtonProps
ariaCheckedInherited From: IButtonProps
boolean
Adds aria-checked to the button element.
ariaControlsInherited From: IButtonProps
string
Adds aria-controls to the button element.
NOTE: Give the base Id in this case, NOT the getSafeId.
ariaDescribedByInherited From: IButtonProps
string
Adds aria-describedby to the button element.
NOTE: Give the base Id in this case, NOT the getSafeId.
ariaDisabledInherited From: IButtonProps
boolean
Adds aria-disabled to the button element.
ariaExpandedInherited From: IButtonProps
boolean
Adds aria-expanded to the button element.
ariaHasPopupInherited From: IButtonProps
boolean
Adds aria-haspopup to the button element.
ariaHiddenInherited From: IButtonProps
boolean
Adds aria-disabled to the button element.
ariaLabelInherited From: IButtonProps
string
Adds aria-label to the button element.
ariaLabelledByInherited From: IButtonProps
string
Adds aria-labelledby to the button element.
ariaPosInSetInherited From: IButtonProps
number
Adds aria-posinset to the button element.
ariaPressedInherited From: IButtonProps
boolean
Adds aria-pressed to the button element.
ariaRoleDescriptionInherited From: IButtonProps
string
Adds aria-roledescription to the button element.
ariaSelectedInherited From: IButtonProps
boolean
Adds aria-selected to the button element.
ariaSetSizeInherited From: IButtonProps
number
Adds aria-setsize to the button element.
autoFocusfalseInherited From: IButtonProps
boolean
If true, the button is focused when mounted.
buttonClassNameInherited From: IExpandableButtonProps
string
Optional className to apply to the button element
classNameInherited From: IButtonProps
string
Optional class name to add to the button element.
contextualMenuPropsrequired
Properties for the menu that appears when the dropdown is shown.
dangerInherited From: IButtonProps
boolean
Set to true if this button should be styled with a danger color.
dataIndexInherited From: IButtonProps
number
An optional data attribute to add to the button element.
disabledInherited From: IButtonProps
boolean
If true, the button cannot be interacted with.
excludeFocusZoneInherited From: IButtonProps
boolean
Set to true if you don't want the button's focus managed by a FocusZone.
excludeTabStopInherited From: IButtonProps
boolean
Set to true if you don't want the button's to be tabbable.
expandKeyKeyCode.DownArrowInherited From: IExpandableSharedProps
KeyCode | KeyCode[]
The key used to expand the components callout.
focusZoneIdInherited From: IButtonProps
string
Set the buttons focus zone to be different than the closest parent focus zone.
hideDropdownIcon
boolean
If hideDropdownIcon is supplied the button acts as a dropdown button
without showing the dropdown arrows.
hrefInherited From: IButtonProps
string
Href to navigate to when the button is clicked. Pass in if this is a link button.
iconPropsInherited From: IButtonProps
Object specifying which icon to display within the button.
idInherited From: IButtonProps
string
A unique identifier for the button
onBlurInherited From: IButtonProps
(event: React.FocusEvent<HTMLElement>) => void
Callback to handle blur events
onClickInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void
Callback to handle button clicks.
onCollapse
() => void
Optional callback to call when the dropdown is collapsed.
onExpand
() => void
Optional callback to call when the dropdown is expanded.
onFocusInherited From: IButtonProps
(event: React.FocusEvent<HTMLElement>) => void
Callback to handle focus events
onKeyDownInherited From: IButtonProps
(event: React.KeyboardEvent<HTMLElement>) => void
Callback to handle button key down.
onMouseDownInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement>) => void
Callback to handle mouse leave events.
onMouseLeaveInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement>) => void
Callback to handle mouse leave events.
onMouseOverInherited From: IButtonProps
(event: React.MouseEvent<HTMLElement> | React.MouseEvent<HTMLElement>) => void
Callback to handle mouse over events.
primaryInherited From: IButtonProps
boolean
Set to true if this button should be styled with a primary color.
relInherited From: IButtonProps
string
Optional, relationship between current document and the linked document. Only required if href is set.
rolebuttonInherited From: IButtonProps
string
Optional aria role.
styleInherited From: IButtonProps
React.CSSProperties
Extra styles that should be added to the element, this supports dynamic
styles that couldn't be defined statically in CSS.
subtleInherited From: IButtonProps
boolean
Set to true to style this as a subtle button.
tabIndexInherited From: IButtonProps
number
Sets the tabindex on the button element.
targetInherited From: IButtonProps
string
Optional,context in which the linked resource will open.
textInherited From: IButtonProps
string
Optional text to render inside the button.
tooltipPropsInherited From: IButtonProps
Optional tooltip to show when the button is hovered.
For icon only buttons, the tooltip will default to the aria-label.
type"button" if href is not set, otherwise undefinedInherited From: IButtonProps
"submit" | "reset" | "button"
Optional, type of button.
ISplitButtonProps
buttonPropsrequired
Props to pass to the main button of the split button.
Primary, Disabled, and Subtle props are overriden by Split button props
buttonRef
string | ((instance: Button | null) => void) | React.RefObject<Button>
Ref of the main button
className
string
Css class(es) to be added to the split button
disabled
boolean
Set to true if both buttons should be disabled.
expandableRef
React.RefObject<Expandable>
/**
* Props to pass to the dropdown button of the split button.
*
* Primary, Disabled, and Subtle props are overriden by Split button props
*/
menuButtonProps: IMenuButtonProps
Ref of the expandable object
primary
boolean
Set to true if both buttons should be styled with the primary style.
renderCallout
() => JSX.Element
subtle
boolean
Set to true if both buttons should be styled with the subtle style.
IClipboardButtonProps
ariaLabel"Copy to clipboard"
string
Aria label to pass to button
className
string
Optional CSS class name to add to Clipboard Button
getContentrequired
() => string | JSX.Element | HTMLElement
Function to retreive the text that will be copied to the clipboard.
This function can return either a plain text string, a new JSX.Element
with the HTML to copy, or an HTMLexisting DOM Element.
onBlur
() => void
Callback provided when the button looses the focus.
onCopy
() => void
Callback provided after a copy is finished.
onFocus
(e: React.FocusEvent) => void
Callback provided when the button gets the focus.
onMouseLeave
(event: React.MouseEvent<HTMLElement>) => void
Callback to handle mouse leave events.
showCopiedTooltip
boolean | string
If set to true, the tooltip will be changed to "Copied to Clipboard" when
the button is clicked.
If a string is provided the tooltip will be changed to the string instead.
subtle
boolean
Set to true to style this as a subtle button.