---
system: material
category: guidance
topic: components/button
content_type: guidance
status: latest
version_label: "M3 (Expressive update May 2025)"
retrieved: 2026-05-12
source_url: https://m3.material.io/components/buttons
derived_from:
  - kb/design-systems/material/guidance/foundations/color-roles
  - kb/design-systems/material/guidance/foundations/typography
  - kb/design-systems/material/guidance/foundations/shape
tags: [component, button, material, interaction, action]
---

# Material Design 3 — Buttons

## Overview

Buttons communicate actions that people can take. They are placed throughout the UI in dialogs, modal windows, forms, cards, and toolbars. Avoid overuse — too many buttons disrupts visual hierarchy.

Five color styles, in order of emphasis:

1. **Filled** — highest emphasis; primary actions
2. **Filled tonal** — medium-high emphasis; secondary actions on primary surfaces
3. **Elevated** — medium emphasis; surfaces requiring slight lift
4. **Outlined** — medium-low emphasis; important but non-primary actions
5. **Text** — lowest emphasis; least critical actions

M3 Expressive (May 2025) adds toggle functionality and two shape variants (round / square) per style.

---

## Variants

### Filled
- Container: `primary` color role
- Label + icon: `on-primary`
- Use for: the single most important action on a screen

### Filled tonal
- Container: `secondary-container`
- Label + icon: `on-secondary-container`
- Use for: alternative primary action; softer presence than filled

### Elevated
- Container: `surface-container-low` + `shadow-1` elevation
- Label + icon: `primary`
- Use for: action that needs lift against a flat surface

### Outlined
- Container: transparent
- Label + icon: `primary`
- Border: `outline` role (1dp)
- Use for: secondary actions where fill would be distracting

### Text
- Container: transparent (visible only on hover/focus/pressed states)
- Label + icon: `primary`
- Use for: lowest-priority actions; link-like appearance in dense lists

---

## Sizes (M3 Expressive)

| Size | Height | Padding (horizontal) |
|---|---|---|
| Extra small | 32dp | 12dp |
| Small (default) | 40dp | 16dp (recommended) or 24dp |
| Medium | 48dp | 20dp |
| Large | 56dp | 24dp |
| Extra large | 64dp | 32dp |

---

## Toggle buttons

Use for binary selections (Save / Favorite). On selection:
- Icon changes from outlined → filled
- Shape morphs: round → square (default behavior)
- Color changes to indicate selected state

Keep label character count similar between selected/unselected states — large label changes are disruptive.

---

## Anatomy

1. **Label text** — required; 1–3 words; sentence case only
2. **Container** — holds label and optional icon
3. **Icon** — optional; leading or trailing; standard size 20dp

**Label rules:**
- Sentence case: "Save changes", not "SAVE CHANGES"
- Container width fits label dynamically — never clip label text

---

## Shapes

Two shape variants per size (M3 Expressive):

**Round:** Fully rounded corners (`shape-full` → 9999px)

**Square:** Corner radius scales with button size:
- Small: `shape-small` (4dp)
- Medium: `shape-medium` (8dp)
- Large: `shape-large` (12dp)
- Extra large: `shape-extra-large` (16dp)

Default shape is **round** for standard buttons.

---

## Color tokens

```css
/* Filled */
--md-filled-button-container-color:    var(--md-sys-color-primary);
--md-filled-button-label-text-color:   var(--md-sys-color-on-primary);

/* Filled tonal */
--md-filled-tonal-button-container-color:   var(--md-sys-color-secondary-container);
--md-filled-tonal-button-label-text-color:  var(--md-sys-color-on-secondary-container);

/* Elevated */
--md-elevated-button-container-color:  var(--md-sys-color-surface-container-low);
--md-elevated-button-label-text-color: var(--md-sys-color-primary);

/* Outlined */
--md-outlined-button-label-text-color: var(--md-sys-color-primary);
--md-outlined-button-outline-color:    var(--md-sys-color-outline);

/* Text */
--md-text-button-label-text-color: var(--md-sys-color-primary);
```

---

## States

State layers use `on-*` color roles at defined opacities applied over the container.

| State | Overlay opacity |
|---|---|
| Hover | 8% |
| Focused | 10% |
| Pressed | 10% |
| Disabled | container 12% opacity; label 38% opacity |

---

## Accessibility

- Minimum touch target: 48×48dp (button may be smaller visually)
- Disabled buttons remain in tab order for discoverability
- Icon-only buttons require `aria-label` equal to the action
- Focus indicator uses `sys.color.secondary` outline (2dp, 2dp offset)
- Toggle buttons: announce state change with `aria-pressed`