Carbon Design System — Button

Overview

Buttons let users trigger actions. Use them for discrete, high-intent tasks — not for navigation. Carbon buttons support seven visual kinds plus an icon-only variant, covering the full range from primary CTAs to destructive danger actions.

Kinds (variants)

Kind	Use
`primary`	Main call to action; one per page/group
`secondary`	Alternative actions alongside primary
`tertiary`	Low-emphasis actions; outline style
`ghost`	Lowest emphasis; text-only appearance
`danger`	Destructive primary actions (delete, remove)
`danger--tertiary`	Destructive but moderate emphasis
`danger--ghost`	Destructive lowest emphasis

One primary button per context. For secondary actions, use secondary, tertiary, or ghost. Never use multiple primary buttons in the same group.

Sizes

Size	Height
`xs`	24px
`sm`	32px
`md`	40px
`lg` (default)	48px
`xl`	64px
`2xl`	80px

Default size is lg (48px). Use sm for compact table toolbars and inline actions.

Icon usage

Import Carbon icons and pass via the renderIcon prop. Icons display trailing by default.

import { Add } from '@carbon/icons-react'

<Button renderIcon={Add} iconDescription="Add item">
  Add item
</Button>

iconDescription is required when using renderIcon — it provides the accessible label for screen readers.

Icon-only buttons

<Button
  hasIconOnly
  renderIcon={Add}
  iconDescription="Add item"
  tooltipAlignment="center"
  tooltipPosition="bottom"
/>

Icon-only buttons require hasIconOnly, renderIcon, and iconDescription. They support primary, secondary, tertiary, and ghost kinds — not danger variants.

A tooltip appears on hover/focus to label the action.

ButtonSet

Group related buttons with ButtonSet. The stacked prop arranges them vertically.

<ButtonSet>
  <Button kind="secondary">Cancel</Button>
  <Button kind="primary">Save</Button>
</ButtonSet>

Order: dismissive/secondary action on left, confirming/primary on right.

Link buttons

Pass href to render the button as an anchor element:

<Button href="/dashboard">Go to dashboard</Button>

For other element types, use as:

<Button as="label" htmlFor="file-upload">Upload file</Button>

Skeleton state

import { ButtonSkeleton } from '@carbon/react'

<ButtonSkeleton />

Use during loading states where a button will appear.

Badge count

Icon buttons support badgeCount for notification indicators:

<Button hasIconOnly renderIcon={Notification} iconDescription="Notifications" badgeCount={3} />

Accessibility

iconDescription maps to aria-label for icon-only buttons
Non-button elements (as prop) need role="button" if they don't render as <a>
Tooltips on icon buttons use aria-label — ensure iconDescription is action-oriented
Focus ring: Carbon's default focus style (2px $focus color outline, 1px offset)
Disabled buttons: use disabled prop which sets aria-disabled and removes from tab order