Allow arbitrary foreground and background elements for ButtonStyle

[caseycrogers]

Is there an existing issue for this?

• I have searched the existing issues
• I have read the guide to filing a bug

Use case

I want to add fairly arbitrary visual details to my app's ElevatedButton's (this feature request applies to all the material button types, but I'll use ElevatedButton as a stand in).

Here are some examples:

1. Adding a linear/radial/etc gradient
2. Adding a border
3. Using a semi-opaque image to texture the button
4. Using an arbitrary box shadow instead of the material elevation system
5. Placing .svgs above, behind and around the button as visual accents

As-is, ButtonStyle limits me to a very narrow range of style customization: shape, color, elevation...

I could create my own button system, but the material buttons do an enormous amount of extremely helpful things (manage splash factory, handle material state, tune visual density to match the platform, etc) that would be a huge hassle to reverse engineer.

Here are some examples of random apps in the wild that have buttons that are not achievable without heavy workarounds.

My app. I use a linear gradient and a border using a complicated work around that puts every elevated button in a stack:

Marvel snap. Marvel snap uses a particularly complex system containing tons of elements:

1. asymmetric shape
2. Texture
3. Texture fades to solid background in center
4. Stroke text
5. Metallic border
6. Light flare
7. And more...

Proposal

I think there are a lot of different ways to add greater customization to ButtonStyle. I will list a few I've thought of here, I'm very open to more suggestions!

1. Mimic Container's foreground and background BoxDecoration arguments
   I don't love this solution as it's fairly limiting. For example, you can't use a Stack to stack elements on top of each other in this context.
2. Include foreground and background builder arguments. The builders would take in a context, the current material state(s) and the EdgeInsets by which the button is padded with (as they should be able to draw in and outside of the button without having to reverse engineer the complicated padding logic).
   I like this much more, as it gives me completely arbitrary design control. For example, even Marvel Snap's insanely complicated button would probably be doable with this system. The implementation would need to ensure the foreground child doesn't interfere with hit testing. The disadvantage is that even pretty simple customizations (like adding a linear gradient) would be pretty complicated.

In both cases, the background argument would be placed between the button's child and the background Material. And/or the Material could be left out entirely if the background argument is non null.

Maybe to ensure that simple customization is easy while complex customization is still possible, BOTH BoxDecoration and builder based customization could be provided?

What this might look like to use (coded off the top of my head, probably has minor syntax errors):

ElevatedButton(
  style: ButtonStyle(
    backgroundBuilder: (context, padding, materialStates, style) {
       final baseColor = style.resolveFor(materialStates);
       final shape = style.shape;
       return Padding(
         // Pad the background by the inherited padding.
         // Elements could be placed above this padding to draw outside
         // of the elevated button's background.
         padding: padding,
         child: _ClipToShape(
           shape: shape, 
           child: Stack(
             children: [
               _MyGradient(color:  baseColor),
               _MySvgAccent(),
               // And so on.
             ],
           )
         ),
       );
    },
  ),
);

[HansMuller]

Good suggestion here and, as you've pointed out, getting the design right means sorting out how to make common cases - like a gradient background - easy, and the tricky cases possible. Leaving the Material background in place is probably important, since it deals with the button's shape. Providing a way to stack a background widget on top of the Material (and clipped to the Material) does seem like a good general purpose idea.

If you're interested in pursuing this further, prototyping some common cases and looking for ways to simplify writing them would be a helpful to continue.

[caseycrogers]

Here's my hacky way of creating an arbitrarily customizable elevated button, if that helps for inspiration:

        return Stack(
          children: [
            Positioned.fill(
              child: Container(
                margin: const EdgeInsets.symmetric(vertical: 4),
                foregroundDecoration: BoxDecoration(
                  borderRadius: BorderRadius.circular(context.gutterTiny),
                  border: Border.all(
                    width: context.gutterTiny,
                    color: Theme.of(context).colorScheme.shadow,
                  ),
                ),
                decoration: BoxDecoration(
                  borderRadius: BorderRadius.circular(context.gutterTiny),
                  gradient: kButtonGradient(context, backgroundColor),
                ),
              ),
            ),
            ElevatedButtonTheme(
              data: ElevatedButtonThemeData(
                style: effectiveStyle.copyWith(
                  backgroundColor:
                      const MaterialStatePropertyAll(Colors.transparent),
                  foregroundColor: MaterialStatePropertyAll(
                    foregroundColor,
                  ),
                ),
              ),
              child: ElevatedButton(
                onPressed: onTap != null ? () => wrap(onTap) : onTap,
                child: ShaderMask(
                  shaderCallback: (bounds) {
                    return LinearGradient(
                      begin: const Alignment(0.005, 1),
                      end: const Alignment(-0.005, -1),
                      stops: const [.2, .55],
                      colors: [
                        Theme.of(context).shadowColor.withOpacity(.1),
                        Theme.of(context).shadowColor.withOpacity(0),
                      ],
                    ).createShader(bounds);
                  },
                  blendMode: BlendMode.srcATop,
                  child: child,
                ),
              ),
            ),
          ],
        );

[HansMuller]

I played around with the ShaderMask part of your example a little (DartPad).

The result is still a little complicated:

ElevatedButton(
  onPressed: () { },
  style: ElevatedButton.styleFrom(
    textStyle: theme.textTheme.displayLarge,
  ).copyWith(
    // Lighten the hovered overlay color a little so that it doesn't
    // obscure the faded part of the shader masked child.
    overlayColor: MaterialStateProperty.resolveWith(
      (Set<MaterialState> states) {
        if (states.contains(MaterialState.hovered)) {
          return colorScheme.primary.withOpacity(0.04);
        }
        return null; // defer to the default
      },
    ),
  ),
  child: ShaderMask(
    shaderCallback: (Rect bounds) {
      return LinearGradient(
        begin: Alignment.bottomCenter,
        end: Alignment.topCenter,
        colors: <Color>[
          colorScheme.primary,
          colorScheme.primaryContainer,
        ],
      ).createShader(bounds);
    },
    blendMode: BlendMode.srcATop,
    child: const Text('Elevated Button'),
  ),
)

Doing so highlighted the fact it's not really practical for the child to respond to state changes in the same way that we'd like to have a background widget (stacked behind the child) also respond to state changes. As well as being informed of the button's shape and the child's insets. I have a vague idea about how to address these limitations without breaking backwards compatibility. The vague idea is that the background (currently the a Material widget) and the foreground (currently just the child) would be constructed by callbacks along the lines of what you've proposed earlier. Will try and make a concrete proposal here soon.

[HansMuller]

This issue is a generalization of #130335 and #89563.

[HansMuller]

Giving a button a gradient background isn't too difficult. Here's an example (DartPad) based on one provided by @TahaTesser in #130335. It requires one to restore the button's padding, by padding the button's child, and the configuration requires turning on clipping and using an Ink widget. As you can see by comparing this example with the previous one, my quick guess about the padding wasn't quite right.

This isn't too complicated:

ElevatedButton(
  onPressed: () {},
  clipBehavior: Clip.antiAlias, // Buttons don't clip their child by default.
  style: ElevatedButton.styleFrom(
    padding: EdgeInsets.zero,  // So that the gradient fills the entire button.
    textStyle: theme.textTheme.displayLarge,
  ),
  child: Ink( // So that the button's overlay continues to appear.
    decoration: BoxDecoration(
      gradient: LinearGradient(
        colors: <Color>[
          colorScheme.primaryContainer,
          colorScheme.tertiaryContainer,
        ],
        begin: Alignment.topLeft,
        end: Alignment.bottomRight,
      ),
    ),
    child: const Padding(
      padding: EdgeInsets.symmetric(horizontal: 16),
      child: Text('Elevated Button'),
    ),
  ),
)

Because the gradient background is introduced as part of the child, it's not possible to configure the ElevatedButtonTheme to give all elevated buttons a gradient background (this is also true for the previous example). And, as before, this example doesn't address creating a background that changes based on the button's state.

[HansMuller]

I've addressed most of the issues described here in #141818. There's a detailed explanation of the new API in the PR's description.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.