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.

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatelessWidget
• IconButton

Implementers

• BackButton
• CloseButton
• DrawerButton
• EndDrawerButton

Constructors

IconButton({Key? key, double? iconSize, VisualDensity? visualDensity, EdgeInsetsGeometry? padding, AlignmentGeometry? alignment, double? splashRadius, Color? color, Color? focusColor, Color? hoverColor, Color? highlightColor, Color? splashColor, Color? disabledColor, required VoidCallback? onPressed, ValueChanged<bool>? onHover, VoidCallback? onLongPress, MouseCursor? mouseCursor, FocusNode? focusNode, bool autofocus = false, String? tooltip, bool? enableFeedback, BoxConstraints? constraints, ButtonStyle? style, bool? isSelected, Widget? selectedIcon, MaterialStatesController? statesController, required Widget icon})

Creates an icon button.

const

IconButton.filled({Key? key, double? iconSize, VisualDensity? visualDensity, EdgeInsetsGeometry? padding, AlignmentGeometry? alignment, double? splashRadius, Color? color, Color? focusColor, Color? hoverColor, Color? highlightColor, Color? splashColor, Color? disabledColor, required VoidCallback? onPressed, ValueChanged<bool>? onHover, VoidCallback? onLongPress, MouseCursor? mouseCursor, FocusNode? focusNode, bool autofocus = false, String? tooltip, bool? enableFeedback, BoxConstraints? constraints, ButtonStyle? style, bool? isSelected, Widget? selectedIcon, MaterialStatesController? statesController, required Widget icon})

Create a filled variant of IconButton.

const

IconButton.filledTonal({Key? key, double? iconSize, VisualDensity? visualDensity, EdgeInsetsGeometry? padding, AlignmentGeometry? alignment, double? splashRadius, Color? color, Color? focusColor, Color? hoverColor, Color? highlightColor, Color? splashColor, Color? disabledColor, required VoidCallback? onPressed, ValueChanged<bool>? onHover, VoidCallback? onLongPress, MouseCursor? mouseCursor, FocusNode? focusNode, bool autofocus = false, String? tooltip, bool? enableFeedback, BoxConstraints? constraints, ButtonStyle? style, bool? isSelected, Widget? selectedIcon, MaterialStatesController? statesController, required Widget icon})

Create a filled tonal variant of IconButton.

const

IconButton.outlined({Key? key, double? iconSize, VisualDensity? visualDensity, EdgeInsetsGeometry? padding, AlignmentGeometry? alignment, double? splashRadius, Color? color, Color? focusColor, Color? hoverColor, Color? highlightColor, Color? splashColor, Color? disabledColor, required VoidCallback? onPressed, ValueChanged<bool>? onHover, VoidCallback? onLongPress, MouseCursor? mouseCursor, FocusNode? focusNode, bool autofocus = false, String? tooltip, bool? enableFeedback, BoxConstraints? constraints, ButtonStyle? style, bool? isSelected, Widget? selectedIcon, MaterialStatesController? statesController, required Widget icon})

Create an outlined variant of IconButton.

const

Properties

alignment → AlignmentGeometry?

Defines how the icon is positioned within the IconButton.

final

autofocus → bool

True if this widget will be selected as the initial focus when no other node in its scope is currently focused.

final

color → Color?

The color to use for the icon inside the button, if the icon is enabled. Defaults to leaving this up to the icon widget.

final

constraints → BoxConstraints?

Optional size constraints for the button.

final

disabledColor → Color?

The color to use for the icon inside the button, if the icon is disabled. Defaults to the ThemeData.disabledColor of the current Theme.

final

enableFeedback → bool?

Whether detected gestures should provide acoustic and/or haptic feedback.

final

focusColor → Color?

The color for the button when it has the input focus.

final

focusNode → FocusNode?

An optional focus node to use as the focus node for this widget.

final

hashCode → int

The hash code for this object.

no setterinherited

highlightColor → Color?

The secondary color of the button when the button is in the down (pressed) state. The highlight color is represented as a solid color that is overlaid over the button color (if any). If the highlight color has transparency, the button color will show through. The highlight fades in quickly as the button is held down.

final

hoverColor → Color?

The color for the button when a pointer is hovering over it.

final

icon → Widget

The icon to display inside the button.

final

iconSize → double?

The size of the icon inside the button.

final

isSelected → bool?

The optional selection state of the icon button.

final

key → Key?

Controls how one widget replaces another widget in the tree.

finalinherited

mouseCursor → MouseCursor?

The cursor for a mouse pointer when it enters or is hovering over the button.

final

onHover → ValueChanged<bool>?

The callback that is called when the button is hovered.

final

onLongPress → VoidCallback?

The callback that is called when the button is long-pressed.

final

onPressed → VoidCallback?

The callback that is called when the button is tapped or otherwise activated.

final

padding → EdgeInsetsGeometry?

The padding around the button's icon. The entire padded icon will react to input gestures.

final

runtimeType → Type

A representation of the runtime type of the object.

no setterinherited

selectedIcon → Widget?

The icon to display inside the button when isSelected is true. This property can be null. The original icon will be used for both selected and unselected status if it is null.

final

splashColor → Color?

The primary color of the button when the button is in the down (pressed) state. The splash is represented as a circular overlay that appears above the highlightColor overlay. The splash overlay has a center point that matches the hit point of the user touch event. The splash overlay will expand to fill the button area if the touch is held for long enough time. If the splash color has transparency then the highlight and button color will show through.

final

splashRadius → double?

The splash radius.

final

statesController → MaterialStatesController?

Represents the interactive "state" of this widget in terms of a set of WidgetStates, like WidgetState.pressed and WidgetState.focused.

final

style → ButtonStyle?

Customizes this button's appearance.

final

tooltip → String?

Text that describes the action that will occur when the button is pressed.

final

visualDensity → VisualDensity?

Defines how compact the icon button's layout will be.

final

Methods

build(BuildContext context) → Widget

Describes the part of the user interface represented by this widget.

override

createElement() → StatelessElement

Creates a StatelessElement to manage this widget's location in the tree.

inherited

debugDescribeChildren() → List<DiagnosticsNode>

Returns a list of DiagnosticsNode objects describing this node's children.

inherited

debugFillProperties(DiagnosticPropertiesBuilder properties) → void

Add additional properties associated with the node.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode

Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.

inherited

toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String

A string representation of this object.

inherited

toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String

Returns a string representation of this node and its descendants.

inherited

toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String

Returns a one-line detailed description of the object.

inherited

toStringShort() → String

A short, textual description of this widget.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

styleFrom({Color? foregroundColor, Color? backgroundColor, Color? disabledForegroundColor, Color? disabledBackgroundColor, Color? focusColor, Color? hoverColor, Color? highlightColor, Color? shadowColor, Color? surfaceTintColor, Color? overlayColor, double? elevation, Size? minimumSize, Size? fixedSize, Size? maximumSize, double? iconSize, BorderSide? side, OutlinedBorder? shape, EdgeInsetsGeometry? padding, MouseCursor? enabledMouseCursor, MouseCursor? disabledMouseCursor, VisualDensity? visualDensity, MaterialTapTargetSize? tapTargetSize, Duration? animationDuration, bool? enableFeedback, AlignmentGeometry? alignment, InteractiveInkFeatureFactory? splashFactory}) → ButtonStyle

A static convenience method that constructs an icon button ButtonStyle given simple values. This method is only used for Material 3.