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(primary: 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(primary: 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:

TypeFlutter implementation
ElevatedElevatedButton
FilledStyled ElevatedButton
Filled TonalStyled ElevatedButton
OutlinedOutlinedButton
TextTextButton

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

See also:

Mixed in types
Annotations

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<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-only, override
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-only, inherited
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<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.