IconButton

MD3 Expressive icon button: four variants, the five-step size scale with narrow / default / wide footprints, round or square shapes, and an optional toggle mode with a selected icon.

Variants

The default variant is filled.

<IconButton variant="tonal" icon={<SearchIcon />} aria-label="Search" />

Sizes and widths

size sets the container height (32 / 40 / 56 / 96 / 136dp for xs–xl, default sm); width makes the container narrow or wide.

<IconButton size="md" width="wide" icon={<EditIcon />} aria-label="Edit" />

Shapes

round (default) or square. The corner tightens while pressed, and a selected toggle swaps round ⇄ square.

Toggle

With toggle, the button becomes a toggle button (aria-pressed). selectedIcon replaces the icon while selected; use selected / onChange(event, selected) for a controlled toggle or defaultSelected for an uncontrolled one.

const [selected, setSelected] = useState(false)

<IconButton
  toggle
  selected={selected}
  onChange={(event, next) => setSelected(next)}
  icon={<FavoriteBorderIcon />}
  selectedIcon={<FavoriteIcon />}
  aria-label="Favorite"
/>

Disabled

A disabled toggle always uses the disabled colors, whether or not it is selected.

Accessibility

• Renders a native <button>: Tab focuses it, and Enter / Space activate it (or toggle it).
• The icon is decorative (aria-hidden), so always give the button an accessible name with aria-label (or aria-labelledby) that describes the action.
• A toggle exposes its state with aria-pressed. Keep one label for both states; use selectedAriaLabel only when the action itself changes (for example "Mute" / "Unmute").
• The touch target is at least 48 × 48dp, even for the smaller sizes.

Props

Prop	Type	Default	Description
defaultSelected	boolean	false	Uncontrolled initial selected state (toggle mode).
icon *	ReactNode	—	The icon (decorative; the button is labelled via aria-label).
onChange	((event: MouseEvent<HTMLButtonElement, MouseEvent>, selected: boolean) => void)	—	Fires with the triggering event and the next selected state when toggled.
selected	boolean	—	Controlled selected state (toggle mode).
selectedAriaLabel	string	—	Accessible label swapped in when selected (toggle mode).
selectedIcon	ReactNode	—	Alternate icon shown while selected in toggle mode.
shape	enum	round	Resting shape; morphs on press and on toggle selection.
size	enum	sm	Container size on the Expressive scale.
toggle	boolean	false	Enable toggle (selectable) behavior with aria-pressed.
variant	enum	filled	Visual emphasis.
width	enum	default	Container width footprint.