Icon button

A compact button that shows one icon. Four types, five sizes and three widths.

Category: Actions
API status: Expressive
Compose APIs: IconButton, FilledIconButton, FilledTonalIconButton, OutlinedIconButton, IconToggleButton, IconButtonDefaults
Interactive page: https://m3e.ljzapps.app/#components/icon-button

When to use

Use an icon button for familiar actions where the icon alone is clear, such as favorite, share or close.

Choose the size with the matching container size from IconButtonDefaults. The width option changes the container without changing the icon, which helps in dense toolbars.

Playground

The interactive page has a playground with live property controls for this component and generated code.

Examples

Types

IconButton(onClick = {}) { Icon(Icons.Rounded.Favorite, contentDescription = "Favorite") }
FilledIconButton(onClick = {}) { Icon(Icons.Rounded.Favorite, contentDescription = "Favorite") }
FilledTonalIconButton(onClick = {}) { Icon(Icons.Rounded.Favorite, contentDescription = "Favorite") }
OutlinedIconButton(onClick = {}) { Icon(Icons.Rounded.Favorite, contentDescription = "Favorite") }

Toggle

The shape morphs between unselected and selected.

var liked by rememberSaveable { mutableStateOf(false) }

FilledIconToggleButton(
    checked = liked,
    onCheckedChange = { liked = it },
    shapes = IconButtonDefaults.toggleableShapes(),
) {
    Icon(
        imageVector = if (liked) Icons.Rounded.Favorite else Icons.Rounded.FavoriteBorder,
        contentDescription = if (liked) "Remove from favorites" else "Add to favorites",
    )
}

Parameters

Name	Type	Default	Description
`onClick`	`() -> Unit`		Called when the button is clicked.
`shapes`	`IconButtonShapes`	`IconButtonDefaults.shapes()`	Resting and pressed shape.
`modifier`	`Modifier`	`Modifier`	Apply Modifier.size(containerSize) to choose a size and width.
`colors`	`IconButtonColors`	`iconButtonColors()`	Container and content colors.
`content`	`@Composable () -> Unit`		Usually a single Icon.

Guidelines

Do:

Use well known icons.
Describe the action, not the icon, in the content description.

Don't:

Do not use an icon button for an action that needs a text label to be understood.
Do not nest an icon button inside another clickable.

Accessibility

Always set a contentDescription on the Icon. Icon buttons have no visible label.
The touch target is at least 48 dp even for the extra small size.
Toggle buttons expose their checked state to assistive technology.