ButtonStyle class Null safety

The visual properties that most buttons have in common.

Buttons and their themes have a ButtonStyle property which defines the visual properties whose default values are to be overridden. The default values are defined by the individual button widgets and are typically based on overall theme's ThemeData.colorScheme and ThemeData.textTheme.

All of the ButtonStyle properties are null by default.

Many of the ButtonStyle properties are MaterialStateProperty objects which resolve to different values depending on the button's state. For example the Color properties are defined with MaterialStateProperty<Color> and can resolve to different colors depending on if the button is pressed, hovered, focused, disabled, etc.

These properties can override the default value for just one state or all of them. For example to create a ElevatedButton whose background color is the color scheme’s primary color with 50% opacity, but only when the button is pressed, one could write:

ElevatedButton(
  style: ButtonStyle(
    backgroundColor: MaterialStateProperty.resolveWith<Color?>(
      (Set<MaterialState> states) {
        if (states.contains(MaterialState.pressed))
          return Theme.of(context).colorScheme.primary.withOpacity(0.5);
        return null; // Use the component's default.
      },
    ),
  ),
)

In this case the background color for all other button states would fallback to the ElevatedButton’s default values. To unconditionally set the button's backgroundColor for all states one could write:

ElevatedButton(
  style: ButtonStyle(
    backgroundColor: MaterialStatePropertyAll<Color>(Colors.green),
  ),
)

Configuring a ButtonStyle directly makes it possible to very precisely control the button’s visual attributes for all states. This level of control is typically required when a custom “branded” look and feel is desirable. However, in many cases it’s useful to make relatively sweeping changes based on a few initial parameters with simple values. The button styleFrom() methods enable such sweeping changes. See for example: TextButton.styleFrom, ElevatedButton.styleFrom, OutlinedButton.styleFrom.

For example, to override the default text and icon colors for a TextButton, as well as its overlay color, with all of the standard opacity adjustments for the pressed, focused, and hovered states, one could write:

TextButton(
  style: TextButton.styleFrom(foregroundColor: Colors.green),
)

To configure all of the application's text buttons in the same way, specify the overall theme's textButtonTheme:

MaterialApp(
  theme: ThemeData(
    textButtonTheme: TextButtonThemeData(
      style: TextButton.styleFrom(foregroundColor: Colors.green),
    ),
  ),
  home: MyAppHome(),
)

Material 3 button types

Material Design 3 specifies five types of common buttons. Flutter provides support for these using the following button classes:

Type	Flutter implementation
Elevated	ElevatedButton
Filled	Styled ElevatedButton
Filled Tonal	Styled ElevatedButton
Outlined	OutlinedButton
Text	TextButton

This sample shows how to create each of the Material 3 button types with Flutter.

To create a local project with this code sample, run:
flutter create --sample=material.ButtonStyle.1 mysample

Constructors

ButtonStyle({MaterialStateProperty<TextStyle?>? textStyle, MaterialStateProperty<Color?>? backgroundColor, MaterialStateProperty<Color?>? foregroundColor, MaterialStateProperty<Color?>? overlayColor, MaterialStateProperty<Color?>? shadowColor, MaterialStateProperty<Color?>? surfaceTintColor, MaterialStateProperty<double?>? elevation, MaterialStateProperty<EdgeInsetsGeometry?>? padding, MaterialStateProperty<Size?>? minimumSize, MaterialStateProperty<Size?>? fixedSize, MaterialStateProperty<Size?>? maximumSize, MaterialStateProperty<double?>? iconSize, MaterialStateProperty<BorderSide?>? side, MaterialStateProperty<OutlinedBorder?>? shape, MaterialStateProperty<MouseCursor?>? mouseCursor, VisualDensity? visualDensity, MaterialTapTargetSize? tapTargetSize, Duration? animationDuration, bool? enableFeedback, AlignmentGeometry? alignment, InteractiveInkFeatureFactory? splashFactory}): Create a ButtonStyle.
const

Properties

alignment → AlignmentGeometry?: The alignment of the button's child.
final
animationDuration → Duration?: Defines the duration of animated changes for shape and elevation.
final
backgroundColor → MaterialStateProperty<Color?>?: The button's background fill color.
final
elevation → MaterialStateProperty<double?>?: The elevation of the button's Material.
final
enableFeedback → bool?: Whether detected gestures should provide acoustic and/or haptic feedback.
final
fixedSize → MaterialStateProperty<Size?>?: The button's size.
final
foregroundColor → MaterialStateProperty<Color?>?: The color for the button's Text and Icon widget descendants.
final
hashCode → int: The hash code for this object.
read-onlyoverride
iconSize → MaterialStateProperty<double?>?: The icon's size inside of the button.
final
maximumSize → MaterialStateProperty<Size?>?: The maximum size of the button itself.
final
minimumSize → MaterialStateProperty<Size?>?: The minimum size of the button itself.
final
mouseCursor → MaterialStateProperty<MouseCursor?>?: The cursor for a mouse pointer when it enters or is hovering over this button's InkWell.
final
overlayColor → MaterialStateProperty<Color?>?: The highlight color that's typically used to indicate that the button is focused, hovered, or pressed.
final
padding → MaterialStateProperty<EdgeInsetsGeometry?>?: The padding between the button's boundary and its child.
final
runtimeType → Type: A representation of the runtime type of the object.
read-onlyinherited
shadowColor → MaterialStateProperty<Color?>?: The shadow color of the button's Material.
final
shape → MaterialStateProperty<OutlinedBorder?>?: The shape of the button's underlying Material.
final
side → MaterialStateProperty<BorderSide?>?: The color and weight of the button's outline.
final
splashFactory → InteractiveInkFeatureFactory?: Creates the InkWell splash factory, which defines the appearance of "ink" splashes that occur in response to taps.
final
surfaceTintColor → MaterialStateProperty<Color?>?: The surface tint color of the button's Material.
final
tapTargetSize → MaterialTapTargetSize?: Configures the minimum size of the area within which the button may be pressed.
final
textStyle → MaterialStateProperty<TextStyle?>?: The style for a button's Text widget descendants.
final
visualDensity → VisualDensity?: Defines how compact the button's layout will be.
final

Methods

copyWith({MaterialStateProperty<TextStyle?>? textStyle, MaterialStateProperty<Color?>? backgroundColor, MaterialStateProperty<Color?>? foregroundColor, MaterialStateProperty<Color?>? overlayColor, MaterialStateProperty<Color?>? shadowColor, MaterialStateProperty<Color?>? surfaceTintColor, MaterialStateProperty<double?>? elevation, MaterialStateProperty<EdgeInsetsGeometry?>? padding, MaterialStateProperty<Size?>? minimumSize, MaterialStateProperty<Size?>? fixedSize, MaterialStateProperty<Size?>? maximumSize, MaterialStateProperty<double?>? iconSize, MaterialStateProperty<BorderSide?>? side, MaterialStateProperty<OutlinedBorder?>? shape, MaterialStateProperty<MouseCursor?>? mouseCursor, VisualDensity? visualDensity, MaterialTapTargetSize? tapTargetSize, Duration? animationDuration, bool? enableFeedback, AlignmentGeometry? alignment, InteractiveInkFeatureFactory? splashFactory}) → ButtonStyle: Returns a copy of this ButtonStyle with the given fields replaced with the new values.
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
override
merge(ButtonStyle? style) → ButtonStyle: Returns a copy of this ButtonStyle where the non-null fields in style have replaced the corresponding null fields in this ButtonStyle.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a non-existent 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
toStringShort() → String: A brief description of this object, usually just the runtimeType and the hashCode.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
override

Static Methods

lerp(ButtonStyle? a, ButtonStyle? b, double t) → ButtonStyle?: Linearly interpolate between two ButtonStyles.

Flutter
material
ButtonStyle class