---
system: carbon
category: guidance
topic: components/button
content_type: guidance
status: latest
version_label: "Carbon v11"
retrieved: 2026-05-12
source_url: https://carbondesignsystem.com/components/button/usage/
derived_from:
  - kb/design-systems/carbon/guidance/foundations/color-system
  - kb/design-systems/carbon/guidance/foundations/typography
tags: [component, button, carbon, ibm, interaction, action]
---

# 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.

```jsx
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

```jsx
<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.

```jsx
<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:

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

For other element types, use `as`:

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

---

## Skeleton state

```jsx
import { ButtonSkeleton } from '@carbon/react'

<ButtonSkeleton />
```

Use during loading states where a button will appear.

---

## Badge count

Icon buttons support `badgeCount` for notification indicators:

```jsx
<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