IconButton class

A Material Design icon button.

An icon button is a picture printed on a Material widget that reacts to touches by filling with color (ink).

Icon buttons are commonly used in the AppBar.actions field, but they can be used in many other places as well.

If the onPressed callback is null, then the button will be disabled and will not react to touch.

Requires one of its ancestors to be a Material widget. In Material Design 3, this requirement no longer exists because this widget builds a subclass of ButtonStyleButton.

The hit region of an icon button will, if possible, be at least kMinInteractiveDimension pixels in size, regardless of the actual iconSize, to satisfy the touch target size requirements in the Material Design specification. The alignment controls how the icon itself is positioned within the hit region.

Icon sizes

When creating an icon button with an Icon, do not override the icon's size with its Icon.size parameter, use the icon button's iconSize parameter instead. For example do this:

IconButton(
  iconSize: 72,
  icon: const Icon(Icons.favorite),
  onPressed: () {
    // ...
  },
),

Avoid doing this:

IconButton(
  icon: const Icon(Icons.favorite, size: 72),
  onPressed: () {
    // ...
  },
),

If you do, the button's size will be based on the default icon size, not 72, which may produce unexpected layouts and clipping issues.

Adding a filled background

Icon buttons don't support specifying a background color or other background decoration because typically the icon is just displayed on top of the parent widget's background. Icon buttons that appear in AppBar.actions are an example of this.

It's easy enough to create an icon button with a filled background using the Ink widget. The Ink widget renders a decoration on the underlying Material along with the splash and highlight InkResponse contributed by descendant widgets.

Material Design 3 introduced new types (standard and contained) of IconButtons. The default IconButton is the standard type. To create a filled icon button, use IconButton.filled; to create a filled tonal icon button, use IconButton.filledTonal; to create a outlined icon button, use IconButton.outlined.

Material Design 3 also treats IconButtons as toggle buttons. In order to not break existing apps, the toggle feature can be optionally controlled by the isSelected property.

If isSelected is null it will behave as a normal button. If isSelected is not null then it will behave as a toggle button. If isSelected is true then it will show selectedIcon, if it false it will show the normal icon.

In Material Design 3, both IconTheme and IconButtonTheme are used to override the default style of IconButton. If both themes exist, the IconButtonTheme will override IconTheme no matter which is closer to the IconButton. Each IconButton's property is resolved by the order of precedence: widget property, IconButtonTheme property, IconTheme property and internal default property value.

In Material Design 3, the IconButton.visualDensity defaults to VisualDensity.standard for all platforms; otherwise the button will have a rounded rectangle shape if the IconButton.visualDensity is set to VisualDensity.compact. Users can customize it by using IconButtonTheme, IconButton.style or IconButton.visualDensity.

See also:

• Icons, the library of Material Icons.
• BackButton, an icon button for a "back" affordance which adapts to the current platform's conventions.
• CloseButton, an icon button for closing pages.
• AppBar, to show a toolbar at the top of an application.
• TextButton, ElevatedButton, OutlinedButton, for buttons with text labels and an optional icon.
• InkResponse and InkWell, for the ink splash effect itself.