applyElevationOverlayColor property

Apply a semi-transparent overlay color on Material surfaces to indicate elevation for dark themes.

Same property as in ThemeData factory. Included for convenience to avoid a copyWith to change it.

In FlexColorScheme it defaults to true. In Flutter ThemeData.from it also default to true, but in ThemeData factory it defaults to false.

Material drop shadows can be difficult to see in a dark theme, so the elevation of a surface should be portrayed with an "overlay" in addition to the shadow. As the elevation of the component increases, the overlay increases in opacity. The applyElevationOverlayColor turns the application of this overlay on or off for dark themes.

If true and brightness is Brightness.dark, a semi-transparent version of ColorScheme.onSurface will be applied on top of Material widgets that have a ColorScheme.surface color. The level of transparency is based on Material.elevation as per the Material Dark theme specification.

If false the surface color will be used unmodified.

Defaults to false in order to maintain backwards compatibility with apps that were built before the Material Dark theme specification was published. New apps should set this to true for any themes where brightness is Brightness.dark.

See also:

• Material.elevation, which effects the level of transparency of the overlay color.
• ElevationOverlay.applyOverlay, which is used by Material to apply the overlay color to its surface color.
• material.io/design/color/dark-theme.html, which specifies how the overlay should be applied.

Known limitations:

Because of how the overlay color application is implemented in Flutter SDK, you will only get overlay color applied in dark mode when this value is true, if the Material surface color being elevated is equal to ThemeData.colorScheme and its ColorScheme.surface color value.

Thus when using color branded surfaces, if you want all Material surfaces in your theme to get an overlay color in dark mode, you must for dark themes only use background colors that are equal to the surface color. Thus when using FlexColorScheme.dark, use a FlexSurfaceMode that starts with equal. That said, if you use heavy color branding, some surfaces may not need any overlay color, so the lack of it might not be an issue with other modes in such themes. For more information about this limitation, see Flutter SDK issue: https://github.com/flutter/flutter/issues/90353