Components

Button

Clickable elements used to perform actions

Migrating from v1

ButtonV2 is built on React Aria and styled with Thumbprint v2 semantic tokens. It keeps the v1 Button prop names (theme, size, width, icon, iconRight, isDisabled, isLoading, accessibilityLabel, onClick) so most call sites can migrate by swapping the import. Two changes are worth noting:

The theme prop adds subtle and alert on top of the v1 options. The size scale expands to small, medium, large, xlarge, and xxlarge; it defaults to xlarge (48px) so a button rendered without an explicit size keeps the height of the v1 large button.

For buttons that look like links, use TextButtonV2. It keeps the v1 TextButton prop names (theme, iconLeft, iconRight) and inherits the surrounding font size and weight.

Button themes

These are the available ButtonV2 styles for use on light background colors.

<ButtonRow>
  <ButtonV2>
    Primary
  </ButtonV2>
  <ButtonV2 theme="secondary">
    Secondary
  </ButtonV2>
  <ButtonV2 theme="tertiary">
    Tertiary
  </ButtonV2>
  <ButtonV2 theme="caution">
    Caution
  </ButtonV2>
</ButtonRow>

Subtle and alert themes

subtle is a low-emphasis neutral button for secondary actions. alert is a high-emphasis, filled treatment for destructive actions such as deleting.

<ButtonRow>
  <ButtonV2 theme="subtle">
    Subtle
  </ButtonV2>
  <ButtonV2 theme="alert">
    Alert
  </ButtonV2>
</ButtonRow>

Use on dark backgrounds

The solid theme works well on dark backgrounds.

<ButtonV2 theme="solid">
  Solid
</ButtonV2>

Sizes

Buttons are xlarge by default. The size prop adjusts the height, horizontal padding, and font size.

<ButtonRow>
  <ButtonV2 size="small">
    Small
  </ButtonV2>
  <ButtonV2 size="medium">
    Medium
  </ButtonV2>
  <ButtonV2 size="large">
    Large
  </ButtonV2>
  <ButtonV2 size="xlarge">
    XLarge
  </ButtonV2>
  <ButtonV2 size="xxlarge">
    XXLarge
  </ButtonV2>
</ButtonRow>

Disabled buttons

The isDisabled prop visually and functionally disables the button.

<ButtonRow>
  <ButtonV2
    isDisabled
    theme="primary"
  >
    Disabled
  </ButtonV2>
</ButtonRow>

Full width buttons

<ButtonV2 width="full">
  Send Quote
</ButtonV2>

Full width on small screens

This button becomes full width on viewports that are smaller than our small breakpoint. The width is auto on larger screens.

<ButtonV2 width="full-below-small">
  Send Quote
</ButtonV2>

Icon within a button

The icon prop accepts any small icon from Thumbprint Icons. This prop renders an icon left within the button.

<ButtonV2 icon={<ContentModifierMessageSmall />}>
  Send Message
</ButtonV2>

Icon right within the button

iconRight renders an icon right within the button.

<ButtonV2 iconRight={<ContentModifierMessageSmall />}>
  Send Message
</ButtonV2>

Button with loading indicator

The isLoading prop should be used when a button is processing. The label is replaced with a LoaderDots animation, and the button is disabled so it can’t be activated while loading.

<ButtonRow>
  <ButtonV2 isLoading>
    Send Quote
  </ButtonV2>
</ButtonRow>

Buttons that look like links

The TextButtonV2 component renders button elements that visually appear as text links. These buttons accept an onClick and render as inline elements.

<>
  The Pro exceeded our expectations and did a fantastic…{' '}
  <TextButtonV2>
    Read more
  </TextButtonV2>
</>

Adding an icon with text

The TextButtonV2 component provides an iconLeft prop to help vertically position icons alongside text.

<TextButtonV2 iconLeft={<NavigationArrowLeftSmall />}>
  Back
</TextButtonV2>

Adding an icon with text on the right

The TextButtonV2 component also allows an icon to the right of the text.

<TextButtonV2 iconRight={<NavigationArrowRightSmall />}>
  Forward
</TextButtonV2>

Icon that inherits color of parent

This icon inherits the color of its parent with theme="inherit".

<div className="white">
  <TextButtonV2
    accessibilityLabel="Close"
    iconLeft={<NavigationCloseMedium />}
    theme="inherit"
  />
</div>

Changing the font size and weight

These buttons inherit the font size and font weight of their container.

<Text size={3}>
  The Pro exceeded our expectations and did a fantastic…{' '}
  <TextButtonV2>
    Read more
  </TextButtonV2>
</Text>

Props

Button

children
Contents displayed within the button.

Type
React.ReactNode
isDisabled
Visually and functionally disables the button.

Type
boolean
Default
false
isLoading
Boolean determining whether the button is in a loading state. When true the text will we replaced with a loading animation and interaction will be disabled.

Type
boolean
Default
false
icon
Icon from Thumbprint Icons to render left within the button. It must be one of the small icons.

Type
React.ReactNode
iconRight
Icon from Thumbprint Icons to render right within the button. It must be one of the small icons.

Type
React.ReactNode
accessibilityLabel
Description of the button’s content. It is required if the button has an icon and no descriptive text.

Type
string
type
Button’s of type submit will submit a form when used within a form element.

Type
'button' | 'submit'
Default
'button'
onClick
Function that will run when the button is clicked on.

Type
(e: React.MouseEvent<HTMLElement>) => void
onMouseEnter
Function that runs when the user hovers on the button.

Type
(e: React.MouseEvent<HTMLElement>) => void
onMouseOver
Function that runs when the user hovers on the button. Unlike onMouseEnter, onMouseOver fires each time a child element receives focus.

Type
(e: React.MouseEvent<HTMLElement>) => void
onFocus
Function that runs when the button receives focus.

Type
(e: React.FocusEvent<HTMLElement>) => void
onMouseLeave
Function that runs when the user hovers away from the button.

Type
(e: React.MouseEvent<HTMLElement>) => void
onBlur
Function that runs when the button loses focus.

Type
(e: React.FocusEvent<HTMLElement>) => void
theme
Controls the button’s background, text, and border color.

Type
'primary' | 'secondary' | 'tertiary' | 'caution' | 'solid'
Default
'primary'
size
Changes the button's line-height, padding, border-radius, and font-size.

Type
'small' | 'large'
Default
'large'
width
Button components are as wide as the content that is passed in. The full option will expand the width to 100% on all screens. full-below-small will expand the width to 100% on devices smaller than our small breakpoint.

Type
'auto' | 'full' | 'full-below-small'
Default
'auto'
dataTestId
A selector hook into the React component for use in automated testing environments.

Type
string
form
Identifies which form to which the button is associated.

Type
string
dataTest
deprecated
A selector hook into the React component for use in automated testing environments.

Note:
Deprecated in favor of the dataTestId prop

Type
string

TextButton

children
Contents displayed within the button.

Type
React.ReactNode
iconLeft
Icon from Thumbprint Icons to render left of the text within TextButton.

Type
React.ReactNode
iconRight
Icon from Thumbprint Icons to render right of the text within TextButton.

Type
React.ReactNode
isDisabled
Visually and functionally disables the button. We discourage the use of this prop since it is difficult to visually indicate that a link is disabled. Consider not rendering the TextButton if it is not interactive.

Type
boolean
Default
false
onClick
Function that will run when the button is clicked on.

Type
(e: React.MouseEvent<HTMLElement>) => void
onMouseEnter
Function that runs when the user hovers on the button.

Type
(e: React.MouseEvent<HTMLElement>) => void
onMouseOver
Function that runs when the user hovers on the button. Unlike onMouseEnter, onMouseOver fires each time a child element receives focus.

Type
(e: React.MouseEvent<HTMLElement>) => void
onFocus
Function that runs when the button receives focus.

Type
(e: React.FocusEvent<HTMLElement>) => void
onMouseLeave
Function that runs when the user hovers away from the button.

Type
(e: React.MouseEvent<HTMLElement>) => void
onBlur
Function that runs when the button loses focus.

Type
(e: React.FocusEvent<HTMLElement>) => void
accessibilityLabel
Description of the button’s content. It is required if the button has an icon and no descriptive text.

Type
string
theme
Controls the button’s background, text, and border color. inherit will make the button inherit color from its parent.

Type
'primary' | 'secondary' | 'tertiary' | 'inherit' | 'caution'
Default
'primary'
type
Button’s of type submit will submit a form when used within a form element.

Type
'button' | 'submit'
Default
'button'
dataTestId
A selector hook into the React component for use in automated testing environments.

Type
string
form
Identifies which form to which the button is associated.

Type
string
width
Button components are as wide as the content that is passed in. The full option will expand the width to 100% on all screens. full-below-small will expand the width to 100% on devices smaller than our small breakpoint.

Type
'auto' | 'full' | 'full-below-small'
dataTest
deprecated
A selector hook into the React component for use in automated testing environments.

Note:
Deprecated in favor of the dataTestId prop

Type
string