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:

Filled — highest emphasis; primary actions
Filled tonal — medium-high emphasis; secondary actions on primary surfaces
Elevated — medium emphasis; surfaces requiring slight lift
Outlined — medium-low emphasis; important but non-primary actions
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

Label text — required; 1–3 words; sentence case only
Container — holds label and optional icon
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

/* 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