Skip to content

Commit 41990f9

Browse files
authored
[material_ui] Add Material 3 Expressive ElevatedButton (flutter#13084)
Adds Material 3 Expressive support to `ElevatedButton`. As with `IconButton` (flutter#12832), apps opt in with `ElevatedButtonThemeData(variant: StyleVariant.material3Expressive)`. Without it, `ElevatedButton` keeps the Material 3 style. With Material 3 Expressive, `ElevatedButton` supports: * Sizes (`ButtonStyle.sizeVariant`): extra small through extra large. Each size has its own height, padding, icon size, label text style, and gap between the icon and the label. * Shapes (`ButtonStyle.shapeVariant`): round and square, including the pressed shape and the shape change when a toggle button is selected. * Toggle buttons: a button with a non-null `isSelected` is selectable, and uses the selected colors and selected semantics when `isSelected` is true. The defaults are generated from the Material Design tokens by a new `ButtonTemplateM3E` in `gen_defaults`. New APIs: * `ElevatedButtonThemeData.variant` and `ElevatedButtonTheme.variantOf`. A theme that doesn't specify `variant` inherits it from the enclosing themes, the same way as `IconButtonThemeData.variant` (flutter#13263). * `ButtonStyleButton.isSelected` and `ElevatedButton.isSelected`. * `sizeVariant` and `shapeVariant` parameters for `ElevatedButton.styleFrom`. <img src="https://gist.githubusercontent.com/QuncCccccc/aba2243afce554b515eec724e62e5650/raw/44b10f43dfb6f42d2c0800928d993cec53df15c2/elevated_button_m3e.png" width="320" alt="Material 3 Expressive ElevatedButton sizes, shapes, toggle buttons, and disabled buttons"> Fixes flutter#194202 Part of flutter#184937 ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent 3c7764b commit 41990f9

10 files changed

Lines changed: 1767 additions & 10 deletions

‎packages/material_ui/lib/src/button_style_button.dart‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ abstract class ButtonStyleButton extends StatefulWidget {
9292
required this.autofocus,
9393
required this.clipBehavior,
9494
this.statesController,
95+
this.isSelected,
9596
this.isSemanticButton = true,
9697
@Deprecated(
9798
'Remove this parameter as it is now ignored. '
@@ -160,6 +161,20 @@ abstract class ButtonStyleButton extends StatefulWidget {
160161
/// {@macro material_ui.inkwell.statesController}
161162
final MaterialStatesController? statesController;
162163

164+
/// Whether this button is in the selected state.
165+
///
166+
/// If null, the button is not selectable. Otherwise, this value is the source
167+
/// of truth for the button's selected state. It is written to
168+
/// [WidgetState.selected] when the button is first built, when a new
169+
/// [statesController] is provided, and whenever [isSelected] changes. It also
170+
/// controls the button's selected semantics. Tapping the button does not
171+
/// change [isSelected]; update it in [onPressed] to create a toggle button.
172+
///
173+
/// Avoid also updating [WidgetState.selected] through [statesController].
174+
/// That changes only the button's appearance, not its semantics, and is
175+
/// overwritten the next time [isSelected] changes.
176+
final bool? isSelected;
177+
163178
/// Determine whether this subtree represents a button.
164179
///
165180
/// If this is null, the screen reader will not announce "button" when this
@@ -254,6 +269,7 @@ abstract class ButtonStyleButton extends StatefulWidget {
254269
void debugFillProperties(DiagnosticPropertiesBuilder properties) {
255270
super.debugFillProperties(properties);
256271
properties.add(FlagProperty('enabled', value: enabled, ifFalse: 'disabled'));
272+
properties.add(FlagProperty('selected', value: isSelected, ifTrue: 'selected'));
257273
properties.add(DiagnosticsProperty<ButtonStyle>('style', style, defaultValue: null));
258274
properties.add(DiagnosticsProperty<FocusNode>('focusNode', focusNode, defaultValue: null));
259275
}
@@ -340,6 +356,9 @@ class _ButtonStyleState extends State<ButtonStyleButton> with TickerProviderStat
340356
internalStatesController = MaterialStatesController();
341357
}
342358
statesController.update(WidgetState.disabled, !widget.enabled);
359+
if (widget.isSelected != null) {
360+
statesController.update(WidgetState.selected, widget.isSelected!);
361+
}
343362
statesController.addListener(handleStatesControllerChange);
344363
}
345364

@@ -367,6 +386,9 @@ class _ButtonStyleState extends State<ButtonStyleButton> with TickerProviderStat
367386
statesController.update(WidgetState.pressed, false);
368387
}
369388
}
389+
if (widget.isSelected != oldWidget.isSelected) {
390+
statesController.update(WidgetState.selected, widget.isSelected ?? false);
391+
}
370392
}
371393

372394
@override
@@ -598,6 +620,7 @@ class _ButtonStyleState extends State<ButtonStyleButton> with TickerProviderStat
598620
container: true,
599621
button: widget.isSemanticButton,
600622
enabled: widget.enabled,
623+
selected: widget.isSelected,
601624
child: _InputPadding(
602625
minSize: minSize,
603626
child: ConstrainedBox(

‎packages/material_ui/lib/src/elevated_button.dart‎

Lines changed: 140 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import 'theme.dart';
2626
import 'theme_data.dart';
2727

2828
part 'generated/elevated_button_defaults_m3.g.dart';
29+
part 'generated/elevated_button_defaults_m3e.g.dart';
2930

3031
/// A Material Design "elevated button".
3132
///
@@ -54,6 +55,17 @@ part 'generated/elevated_button_defaults_m3.g.dart';
5455
/// If [onPressed] and [onLongPress] callbacks are null, then the
5556
/// button will be disabled.
5657
///
58+
/// To use the Material 3 Expressive style, set
59+
/// [ElevatedButtonThemeData.variant] to [StyleVariant.material3Expressive].
60+
/// The Expressive size and shape variants can then be selected with
61+
/// [ButtonStyle.sizeVariant] and [ButtonStyle.shapeVariant], and the button
62+
/// becomes a toggle button when [isSelected] is non-null.
63+
///
64+
/// With the Material 3 style, [isSelected] updates [WidgetState.selected] and
65+
/// the button's semantics, but the default style doesn't change the button's
66+
/// appearance when it's selected. To show the selected state, use a [style]
67+
/// that resolves [WidgetState.selected].
68+
///
5769
/// <callout-box>
5870
///
5971
/// This sample produces an enabled and a disabled ElevatedButton.
@@ -87,6 +99,7 @@ class ElevatedButton extends ButtonStyleButton {
8799
super.autofocus = false,
88100
super.clipBehavior,
89101
super.statesController,
102+
super.isSelected,
90103
required super.child,
91104
}) : _addPadding = false;
92105

@@ -96,6 +109,10 @@ class ElevatedButton extends ButtonStyleButton {
96109
/// The icon and label are arranged in a row and padded by 12 logical pixels
97110
/// at the start, and 16 at the end, with an 8 pixel gap in between.
98111
///
112+
/// With the Material 3 Expressive style, the padding and the gap between the
113+
/// icon and the label depend on [ButtonStyle.sizeVariant]. See
114+
/// [defaultStyleOf].
115+
///
99116
/// If [icon] is null, this constructor will create an [ElevatedButton]
100117
/// that doesn't display an icon.
101118
///
@@ -112,6 +129,7 @@ class ElevatedButton extends ButtonStyleButton {
112129
super.autofocus = false,
113130
super.clipBehavior = Clip.none,
114131
super.statesController,
132+
super.isSelected,
115133
Widget? icon,
116134
required Widget label,
117135
IconAlignment? iconAlignment,
@@ -163,6 +181,16 @@ class ElevatedButton extends ButtonStyleButton {
163181
/// create a [WidgetStateProperty] with a single value for all
164182
/// states.
165183
///
184+
/// The [sizeVariant] and [shapeVariant] parameters are Material 3 Expressive
185+
/// options. They provide extra-small through extra-large sizes and round or
186+
/// square shapes through [ButtonStyle.sizeVariant] and
187+
/// [ButtonStyle.shapeVariant].
188+
///
189+
/// When [ElevatedButtonThemeData.variant] is
190+
/// [StyleVariant.material3Expressive] and these properties are null,
191+
/// Material 3 Expressive [ElevatedButton] defaults use
192+
/// [ButtonSizeVariant.small] and [ButtonShapeVariant.round].
193+
///
166194
/// All parameters default to null, by default this method returns
167195
/// a [ButtonStyle] that doesn't override anything.
168196
///
@@ -223,6 +251,8 @@ class ElevatedButton extends ButtonStyleButton {
223251
InteractiveInkFeatureFactory? splashFactory,
224252
ButtonLayerBuilder? backgroundBuilder,
225253
ButtonLayerBuilder? foregroundBuilder,
254+
ButtonSizeVariant? sizeVariant,
255+
ButtonShapeVariant? shapeVariant,
226256
}) {
227257
final WidgetStateProperty<Color?>? overlayColorProp = switch ((foregroundColor, overlayColor)) {
228258
(null, null) => null,
@@ -276,6 +306,8 @@ class ElevatedButton extends ButtonStyleButton {
276306
splashFactory: splashFactory,
277307
backgroundBuilder: backgroundBuilder,
278308
foregroundBuilder: foregroundBuilder,
309+
sizeVariant: sizeVariant,
310+
shapeVariant: shapeVariant,
279311
);
280312
}
281313

@@ -397,13 +429,95 @@ class ElevatedButton extends ButtonStyleButton {
397429
///
398430
/// For the [ElevatedButton.icon] factory, the start (generally the left) value of
399431
/// [ButtonStyle.padding] is reduced from 24 to 16.
432+
///
433+
/// ## Material 3 Expressive defaults
434+
///
435+
// TODO(QuncCccccc): Clean up [ThemeData.useMaterial3] once useMaterial3 is removed.
436+
/// If [ThemeData.useMaterial3] is true and [ElevatedButtonThemeData.variant]
437+
/// is [StyleVariant.material3Expressive], the following defaults will be
438+
/// used. Values listed per size are for [ButtonSizeVariant.xSmall],
439+
/// [ButtonSizeVariant.small], [ButtonSizeVariant.medium],
440+
/// [ButtonSizeVariant.large], and [ButtonSizeVariant.xLarge] respectively.
441+
/// The selected values only apply when [isSelected] is non-null.
442+
///
443+
/// * `textStyle` - based on [ButtonStyle.sizeVariant]
444+
/// * xSmall or small - Theme.textTheme.labelLarge
445+
/// * medium - Theme.textTheme.titleMedium
446+
/// * large - Theme.textTheme.headlineSmall
447+
/// * xLarge - Theme.textTheme.headlineLarge
448+
/// * `backgroundColor`
449+
/// * disabled - Theme.colorScheme.onSurface(0.1)
450+
/// * selected - Theme.colorScheme.primary
451+
/// * others - Theme.colorScheme.surfaceContainerLow
452+
/// * `foregroundColor`
453+
/// * disabled - Theme.colorScheme.onSurface(0.38)
454+
/// * selected - Theme.colorScheme.onPrimary
455+
/// * others - Theme.colorScheme.primary
456+
/// * `overlayColor`
457+
/// * selected
458+
/// * hovered - Theme.colorScheme.onPrimary(0.08)
459+
/// * focused or pressed - Theme.colorScheme.onPrimary(0.1)
460+
/// * hovered - Theme.colorScheme.primary(0.08)
461+
/// * focused or pressed - Theme.colorScheme.primary(0.1)
462+
/// * `shadowColor` - Theme.colorScheme.shadow
463+
/// * `surfaceTintColor` - Colors.transparent
464+
/// * `elevation`
465+
/// * disabled - 0
466+
/// * others - 1
467+
/// * `padding` - based on [ButtonStyle.sizeVariant]; horizontal(12),
468+
/// horizontal(16), horizontal(24), horizontal(48), horizontal(64)
469+
/// * `minimumSize` - based on [ButtonStyle.sizeVariant]; Size(64, 32),
470+
/// Size(64, 40), Size(64, 56), Size(64, 96), Size(64, 136)
471+
/// * `fixedSize` - null
472+
/// * `maximumSize` - Size.infinite
473+
/// * `iconSize` - based on [ButtonStyle.sizeVariant]; 20, 20, 24, 32, 40
474+
/// * `iconColor` - same as `foregroundColor`
475+
/// * `side` - null
476+
/// * `shape` - based on [ButtonStyle.sizeVariant], [ButtonStyle.shapeVariant],
477+
/// and state
478+
/// * pressed - RoundedRectangleBorder with radius 8, 8, 12, 16, 16
479+
/// * selected
480+
/// * round - RoundedRectangleBorder with radius 12, 12, 16, 28, 28
481+
/// * square - StadiumBorder()
482+
/// * others
483+
/// * round - StadiumBorder()
484+
/// * square - RoundedRectangleBorder with radius 12, 12, 16, 28, 28
485+
/// * `mouseCursor` - WidgetStateMouseCursor.adaptiveClickable
486+
/// * `visualDensity` - VisualDensity.standard
487+
/// * `tapTargetSize` - MaterialTapTargetSize.padded
488+
/// * `animationDuration` - kThemeChangeDuration
489+
/// * `enableFeedback` - true
490+
/// * `alignment` - Alignment.center
491+
/// * `splashFactory` - Theme.splashFactory
492+
/// * `sizeVariant` - ButtonSizeVariant.small
493+
/// * `shapeVariant` - ButtonShapeVariant.round
494+
///
495+
/// For the [ElevatedButton.icon] factory, the padding is the same, and the
496+
/// gap between the icon and the label is 4, 8, 8, 12, or 16 based on
497+
/// [ButtonStyle.sizeVariant].
400498
401499
@override
402500
ButtonStyle defaultStyleOf(BuildContext context) {
403501
final ThemeData theme = Theme.of(context);
404502
final ColorScheme colorScheme = theme.colorScheme;
503+
final ElevatedButtonThemeData elevatedButtonTheme = ElevatedButtonTheme.of(context);
504+
final StyleVariant effectiveVariant = ElevatedButtonTheme.variantOf(context);
505+
final ButtonSizeVariant? effectiveSize =
506+
style?.sizeVariant ?? elevatedButtonTheme.style?.sizeVariant;
507+
final ButtonShapeVariant? effectiveShape =
508+
style?.shapeVariant ?? elevatedButtonTheme.style?.shapeVariant;
509+
final bool useExpressive =
510+
theme.useMaterial3 && effectiveVariant == StyleVariant.material3Expressive;
405511
final ButtonStyle buttonStyle = theme.useMaterial3
406-
? _ElevatedButtonDefaultsM3(context)
512+
? switch (effectiveVariant) {
513+
StyleVariant.material3 => _ElevatedButtonDefaultsM3(context),
514+
StyleVariant.material3Expressive => _ElevatedButtonDefaultsM3E(
515+
context,
516+
isSelected != null,
517+
effectiveSize,
518+
effectiveShape,
519+
),
520+
}
407521
: styleFrom(
408522
backgroundColor: colorScheme.primary,
409523
foregroundColor: colorScheme.onPrimary,
@@ -426,6 +540,12 @@ class ElevatedButton extends ButtonStyleButton {
426540
splashFactory: InkRipple.splashFactory,
427541
);
428542

543+
// The Material 3 Expressive defaults use the same padding with or without
544+
// an icon.
545+
if (useExpressive) {
546+
return buttonStyle;
547+
}
548+
429549
// Only apply padding when the ElevatedButton has an Icon.
430550
if (_addPadding) {
431551
final double defaultFontSize =
@@ -491,19 +611,33 @@ class _ElevatedButtonWithIconChild extends StatelessWidget {
491611

492612
@override
493613
Widget build(BuildContext context) {
494-
final double defaultFontSize =
495-
buttonStyle?.textStyle?.resolve(const <WidgetState>{})?.fontSize ?? 14.0;
496-
final double scale =
497-
clampDouble(MediaQuery.textScalerOf(context).scale(defaultFontSize) / 14.0, 1.0, 2.0) - 1.0;
498614
final ElevatedButtonThemeData elevatedButtonTheme = ElevatedButtonTheme.of(context);
615+
final bool useExpressive =
616+
Theme.of(context).useMaterial3 &&
617+
ElevatedButtonTheme.variantOf(context) == StyleVariant.material3Expressive;
618+
final double spacing;
619+
if (useExpressive) {
620+
final ButtonSizeVariant effectiveSize =
621+
buttonStyle?.sizeVariant ??
622+
elevatedButtonTheme.style?.sizeVariant ??
623+
ButtonSizeVariant.small;
624+
spacing = _ElevatedButtonDefaultsM3E.iconLabelSpace(effectiveSize);
625+
} else {
626+
final double defaultFontSize =
627+
buttonStyle?.textStyle?.resolve(const <WidgetState>{})?.fontSize ?? 14.0;
628+
final double scale =
629+
clampDouble(MediaQuery.textScalerOf(context).scale(defaultFontSize) / 14.0, 1.0, 2.0) -
630+
1.0;
631+
spacing = lerpDouble(8, 4, scale)!;
632+
}
499633
final IconAlignment effectiveIconAlignment =
500634
iconAlignment ??
501635
elevatedButtonTheme.style?.iconAlignment ??
502636
buttonStyle?.iconAlignment ??
503637
IconAlignment.start;
504638
return Row(
505639
mainAxisSize: MainAxisSize.min,
506-
spacing: lerpDouble(8, 4, scale)!,
640+
spacing: spacing,
507641
children: effectiveIconAlignment == IconAlignment.start
508642
? <Widget>[icon, Flexible(child: label)]
509643
: <Widget>[Flexible(child: label), icon],

0 commit comments

Comments
 (0)