No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

Button

A Button triggers a single action or event. Use it to submit a form (Save), to advance to the next step in a process (Next), or to create a new item (New).

Contents

Quickstart

import Button from "carbon-react/lib/components/button";

Examples

Primary Buttons

For the single most prominent call to action on the page (e.g. Save, Submit, Continue).

Primary buttons can be destructive.

Primary buttons can be disabled.

Primary buttons can have an icon positioned before or after the text.

Primary buttons can be fullWidth.

Primary buttons can be set into noWrap mode to prevent text wrapping.

Secondary Buttons

Less prominent, there can be multiple secondary buttons on a page. Secondary buttons are transparent, rather than white.

Secondary buttons can be destructive.

Secondary buttons can be disabled.

Secondary buttons can have an icon positioned before or after the text.

Secondary buttons can be fullWidth.

Secondary buttons can be set into noWrap mode to prevent text wrapping.

Tertiary Buttons

Tertiary or ‘ghost’ buttons are used for reversing actions, like ‘Cancel’ or ‘Back’.

Tertiary buttons can be destructive.

Tertiary buttons can be disabled.

Tertiary buttons can have an icon positioned before or after the text.

Tertiary buttons can be fullWidth.

Tertiary buttons can be set to noWrap mode to prevent text wrapping.

Dashed Buttons

Dashed buttons are used for adding new content that replaces empty states.

Dashed buttons can be disabled.

Dashed buttons can have an icon positioned before or after the text.

Dashed buttons can be fullWidth.

Dashed buttons can be set to noWrap mode to prevent text wrapping.

Passing in the href prop will render an anchor with role="button" and the Button styles. The target and rel props are also available.

Icon Only Button

Buttons can be rendered with just an icon.

Icon only buttons can also display a tooltip message when the icon is hovered over. This can be acheived by passing a string to the iconTooltipMessage prop.

Props

Options shared between all of the above types of buttons. When setting padding we recommend using either the p, py or px props to ensure the spacing within the button is applied evenly.

Button

NameDescriptionDefault
Margin
m
Margin, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
mt
Margin top, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
mr
Margin right, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
mb
Margin bottom, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
ml
Margin left, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
mx
Margin left/right, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
my
Margin top/bottom, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
Padding
p
Padding, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
pt
Padding top, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
1px
pr
Padding right, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
pb
Padding bottom, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
1px
pl
Padding left, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
px
Padding left/right, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
24px
py
Padding top/bottom, an integer multiplier of the base spacing constant (8px) or any valid CSS string.
numberstring
-
NameDescriptionDefault
aria-label

Prop to specify the aria-label text. Only to be used in Button when only an icon is rendered. This is required to comply with WCAG 4.1.2 - Buttons must have discernible text

string
-
buttonType
Color variants for new business themes: "primary" | "secondary" | "tertiary" | "darkBackground"
"primary""secondary""tertiary""dashed""darkBackground"
-
children
The text the button displays
ReactNode
-
name
Name attribute
string
-
disabled
Apply disabled state to the button
boolean
false
destructive
Apply destructive style to the button
boolean
false
forwardRef
Ref to be forwarded
MutableRefObject<HTMLButtonElement | null> | ((instance: HTMLButtonElement | null) => void) | null
-
fullWidth
Apply fullWidth style to the button
boolean
false
href
Used to transform button into anchor
string
-
iconPosition
Defines an Icon position related to the children: "before" | "after"
"before""after"
"before"
iconTooltipMessage
Provides a tooltip message when the icon is hovered.
string
-
iconTooltipPosition
Provides positioning when the tooltip is displayed.
"top""bottom""left""right"
-
iconType
Defines an Icon type within the button
"filter""key""add""admin""alert""analysis""arrow""arrow_down"
-
noWrap
If provided, the text inside a button will not wrap
boolean
-
onBlur
Specify a callback triggered on blur
((ev: FocusEvent<HTMLButtonElement, Element>) => void)
-
onChange
Specify a callback triggered on change
((ev: ChangeEvent<HTMLButtonElement>) => void)
-
onFocus
Specify a callback triggered on focus
((ev: FocusEvent<HTMLButtonElement, Element>) => void)
-
onKeyDown
Specify a callback triggered on keyDown
((ev: KeyboardEvent<HTMLButtonElement>) => void)
-
onClick
onClick handler
((event: MouseEvent<HTMLButtonElement | HTMLAnchorElement, MouseEvent>) => void)
-
size
Assigns a size to the button: "small" | "medium" | "large"
"small""medium""large"
"medium"
subtext
Second text child, renders under main text, only when size is "large"
string
""
type
HTML button type property
string
-
target
HTML target attribute
string
-
rel
HTML rel attribute
string
-