Migration Guide
This chapter contains guides for the minimum required changes to move from a lower major version to the next higher major one.
Migrating to Version 6.0#
All members that were deprecated in version 5.1 or earlier but still present in versions before 6.0.0 have been removed. To make migration easier, make sure in version 5.1 that you are not using any of its deprecated APIs.
Version 5.1 will still tell you which members are deprecated and what you should replace them with. In this version, those members are totally removed and there is no longer any deprecation guidance for them.
Changes made to increase Material 3 style-compliance
FlexColorScheme version 6 has some default style changes that are breaking with previous used defaults. All style changes concern FlexColorScheme defaults when opting in on Material 3.
Some widgets that in the Flutter SDK have received correct Material 3 design, now also in FlexColorScheme when opting in on Material 3, default to their actual Material 3 default styles. Previously, they may have used a Material 2 style that was Material 3 inspired, but not entirely in-line with Material 3.
ElevatedButton#
The most common breaking style change you may run into, is that the ElevatedButton
has a completely new default color style in Material 3, over Material 2. This may surprise users of previous versions, of FlexColorScheme that had opted in on Material 3. The ElevatedButton
in FCS previously did not use the correct default M3 style in M3 mode, it used the M2 style also in M3 mode. You can either adopt the new default Material 3 style or theme the ElevatedButton
back to its M2 style in M3 mode, by setting background color to primary
and the foreground color to surface
or onPrimary
, which you can do e.g. with:
subThemesData: const FlexSubThemesData(
elevatedButtonSchemeColor: SchemeColor.onPrimary,
elevatedButtonSecondarySchemeColor: SchemeColor.primary,
),
FAB Usage of Global Border Radius#
The FlexSubThemesData.fabUseShape
opinionated component theme style default was changed from true
to false
, this breaks previous default style where FAB also by default got border radius from the global FCS border radius setting. The opinionated style change was done to use a style that by default matches M3 style when ThemeData.useMaterial3
is true
. If you had kept FlexSubThemesData.fabUseShape
unspecified and relied on default value in a previous version, you must set it to true
to get the same result as before.
New M3 Chip Styles#
When opting in on useMaterial3
. When true
it now uses actual M3 styled Chips
instead of its own opinionated custom style, also when the opinionated component sub-themes are enabled. To get the same opinionated coloring as before, but on the M3 styled chips when using M3, set component sub-themes data
subThemesData: const FlexSubThemesData(
chipSchemeColor: SchemeColor.primary
),
Migrating to Version 5.0#
FlexColorScheme version 5 is style wise a big breaking change since all the built-in color schemes the produced themes use, have been revised to follow the new Flutter 2.10.0 Material 3 based ColorScheme
. The color changes to the built-in schemes have been kept minimal compared to previous styles.
Mostly new color values were added to provide support for all the new colors in the Flutter Material 3 ColorScheme
update that landed in Flutter 2.10.0. The new colors are style aligned with past styles as far possible, while also keeping them inline with the Material 3 ColorScheme design intent.
As ColorScheme.primaryVariant
and secondaryVariant
have been deprecated in Flutter 2.10 SDK, so have they in FlexColorScheme. All past color constants for all color values and helper classes with the name "variant" in them have been self-deprecated in FlexColorScheme. The variant color values still exist. If you have used any of them directly, they still work. The old built-in variant color values will remain available at least until version 6.0, maybe even 7.0 if so requested by users.
Breaking: Requires at least Flutter 2.10.0#
Version 5.0.0 requires at least Flutter version 2.10.0 to work. This breaking change is required since the new color properties in ColorScheme
do not exist in any stable version of Flutter before version 2.10.
Breaking: surfaceStyle
removed#
In version 5, the in version 4.2.0 deprecated property surfaceStyle
, including all its implementing classes, enums, helpers and tests have been removed.
- Removed property:
surfaceStyle
inFlexColorScheme.light
andFlexSchemeData.light
. - Removed property:
surfaceStyle
inFlexColorScheme.dark
andFlexSchemeData.dark
. - Removed: enum
FlexSurface
, that onlysurfaceStyle
was using. - Removed: factory
FlexSchemeSurfaceColors.from
that was used to create surface using thesurfaceStyle
. The factoryFlexSchemeSurfaceColors.blend
replaced it in version 4.0.0 already, when usingsurfaceMode
andblendLevel
.
Migration: Use surfaceMode
and blendLevel
instead, it has more blend styles and finer blend granularity than the removed surfaceStyle
.
theme: FlexThemeData.light(
scheme: FlexScheme.flutterDash,
surfaceMode: FlexSurfaceMode.highScaffoldLowSurface,
blendLevel: 20,
),
Breaking: FlexSubThemesData.navigationBarIsStyled
removed#
The property navigationBarIsStyled
in FlexSubThemesData
has been removed. If you have used it, it has a broader more general replacement called FlexSubThemesData.useFlutterDefaults
.
Migration: Consider using useFlutterDefaults
instead, or set style manually using individual properties to desired style matching Flutter defaults un-themed component designs.
Breaking: FlexColorScheme.useSubThemes
no function#
Deprecated property useSubThemes
. This property has no function after 4.2.0 stable and 5.0.0-dev.1. Previously setting this property to true activated the default set and configuration of the optional opinionated component sub-themes, even if you did not pass any FlexSubThemesData()
configuration data to subThemesData
. Before when useSubThemes
was true and no subThemesData
defined, it created one internally using the default constructor FlexSubThemesData()
and used it. It also ignored any defined and to subThemesData
assigned one, if the flag was set to false.
The default component sub-themes are now instead always activated and created by explicitly assigning at least a default constructor FlexSubThemesData()
to FlexColorScheme.subThemesData
.
Migration: If you previously had only set FlexColorScheme.useSubThemes
to true and not specified any subThemesData
properties, you must now add the default constructor. Likewise, if you had set FlexColorScheme.useSubThemes
to false, and had a FlexColorScheme.subThemesData
defined, you must remove it to stop using it. If you need to toggle it ON and OFF, use a bool to enable and disable it, then pass in the FlexSubThemesData
when enabled, and null when not using it.
Why was this change made? Deprecating this property makes the API more consistent. It now follows the same design that is used for the new keyColors
when using FlexKeyColors
, and tones
with FlexTones
. Setting the property useSubThemes
will not cause an error, it just has no effect. You can safely remove it. The property useSubThemes
will be completely removed in release 6.0.
Change: Custom and "internal" m3TextTheme revised.#
Style breaking with 4.2.0 and 5.0.0-dev.x, breaks past used style when opting in on component themes and its optional custom m3TextTheme
enabled. The updated custom implementation of it now follows the implementation used in the Flutter master channel, apart from this issue, where it for now implements the value used in the M3 Web guide. The changes in styles otherwise concern the addition of the font geometry, height, which the previous custom implementation did not have. The usage of the custom m3TextTheme
should be considered internal and temporary, it will be changed to use the actual Flutter implementation once PR #97829 lands in the Flutter stable channel.
Change: Color definitions for ThemeData
colors primaryColorLight
, primaryColorDark
and secondaryHeaderColor
#
Style breaking with 4.2.0 and 5.0.0-dev.x, breaks past used styles on these rarely used colors. The new colors are better. These ThemeData
colors are on a deprecation path and will likely receive some new none MaterialColor
dependent color defaults when that change happens. The new ColorScheme.primary
computed colors for the above rarely used colors are better balanced than before and work well regardless of used ColorScheme.primary
shade and tint.
Change: Color definition for FlexColor.espressoLightPrimary
color was changed#
Style breaking with 4.2.0: Breaks past used color for this color and theme where used.
The color was changed from 0xFF220804 to 0xFF452F2B. Past color was too dark brown to be very usable in a UI. It was very black coffee like, but not very practical in a UI, it was too close to black. Since version 5 is anyway major style breaking with the introduction of the new Material 3 ColorScheme, the opportunity to improve this color used in the espresso
theme was used.
Beware: SchemeColor
values and order, potentially breaking#
The enum SchemeColor
has new values and past values are in a new order.
The order was changed to accommodate all the new color values, and to keep them in
the same order as their corresponding color properties in Flutter Material 3
ColorScheme
color values. The change of order is potentially breaking,
but highly unlikely to break anything in major ways in normal usage.
Deprecated: primaryVariant
and secondaryVariant
#
The colors primaryVariant
and secondaryVariant
in FlexColorScheme are deprecated and can no longer be used to set colors values that result in any color values in Flutter SDK deprecated same named ColorScheme
color properties.
The ColorScheme
deprecated properties primaryVariant
and secondaryVariant
will always get their Flutter SDK default values, regardless of what input you give to them in FlexColorScheme. Flutter sets its deprecated primaryVariant
equal to primary
and secondaryVariant
equal to secondary
.
This means that if your application used those color scheme values on any custom widgets, their colors will change if you upgrade from a previous version of FlexColorScheme and don't do any other changes. You need to migrate to use primaryContainer
, secondaryContainer
, tertiary
or tertiaryContainer
color, as replacement colors in your custom widgets. Which one to use depends on your color design.
If you use a FlexColorScheme
setup made for a version before version 5.0,
with version 5.0, and
- if you have used custom color schemes where you defined the
FlexColorScheme
propertiesprimaryVariant
andsecondaryVariant
- or defined and used them via custom
FlexSchemeColors
, in thecolors
property inFlexColorScheme
.
Then, in those cases the variant color properties will function as fallback input for color properties primaryContainer
and secondaryContainer
respectively, unless own color values for these properties are provided.
When you upgrade the package version to 5.0.0 and have used custom color schemes, you will find your custom variant colors on the corresponding new container colors. Be aware though that past variant color shades are not necessarily a great fit for a Material 3 design intent of container colors, but at least you will get your past custom colors used in the new theme by default.
Migration: Define new custom colors values for all container colors and tertiary color. Use them to make your custom FlexColorScheme
instead. Then migrate away from using Flutter SDK ColorScheme
colors primaryVariant
and secondaryVariant
anywhere in your application. Prefer using its new ColorScheme
color properties as fitting with your design. This is something you have to do after Flutter 2.10, even if you are not using FlexColorScheme. Sure, not immediately, but eventually when the Flutter SDK ColorScheme
colors primaryVariant
and secondaryVariant
are removed after a year or so.
Info: Built-in schemes#
To use the updated built-in Material 3 compatible color schemes, you don't have to migrate anything. All built-in schemes have been migrated to provide color values for all the new Material 3 ColorScheme
color properties.
This migration was done as follows:
- primary, same color as before.
- primaryContainer, this is a new color value added to all built-in schemes.
- secondary, same color as before.
- secondaryContainer, this is a new color value added to all built-in schemes.
- tertiary, this is the same color value as past
secondaryVariant
color. - tertiaryContainer, this is a new color value added to all built-in schemes.
The new color values follow the same design intent the built-in scheme had before, but due to all the new colors in Material 3 ColorScheme, new values had to be added as listed above. The color values used for past primaryVariant
did not really fit anywhere in the new M3 design. However, past color value for secondaryVariant
was reused as the color value for the new tertiary
color.
In Material 2 color design, the variant color was typically a darker color of its primary or secondary counterpart. In M3 design in light theme mode, the container color is intended to be a lighter version of its none container color. In dark mode it is the reverse, container is a darker version of its none container version. If you are lazy when you make custom light and dark themes, you can get away with defining only the primary, secondary, tertiary and their container colors, for your light theme mode. If you follow the container's design intent to be a lighter version of its none container version, you can often for dark mode just swap light mode none container and container color values from your light mode, and you will get a fairly decent dark mode theme.
Depending on your settings, FlexColorScheme computes different colors and shades for all the surface, background and onColors. You can also choose whether you use the new Material 3 error colors, instead of the Material 2 based error colors, even if you are not using seed-generated Material 3 color schemes.
The past Material 2 error colors have received some new for FlexColorScheme chosen color values to fill the gaps in the ColorScheme error colors when using their Material 2 version. So even it has proper color shades for all containers and onColors for both light and dark mode, they are slightly different from their Material 3 version and more inline with the Material 2 style.
Migrating to Version 4.0#
The in FlexColorScheme version 3.0 deprecated member accentColor
was completely removed. It had no function starting from version 3.0.
There are no other broken properties, however the property darkIsTrueBlack
contains a minor breaking style change with previous styles, it now makes surface color 8% darker instead of 6%.
For more information on this and on all the new features, see changelog.
Migrating to Version 3.0#
FlexColorScheme property accentColor
was deprecated, it is still present but has no function. It will be completely removed in version 4 of FlexColorScheme. The property was removed, because it is going to be removed in Flutter SDK ThemeData
, starting from the Flutter version v2.3.0-0.1.pre. Use property secondaryColor
in FlexColorScheme instead.
For more information on this and on new features, see changelog.
Migrating to Version 2.0#
Version 2.0 is the first stable release of FlexColorScheme with null safety. To migrate to it, you should use minimum Dart SDK version 2.12 and perform normal Dart null safety migration of your application.
The in version 1.3.0 deprecated member FlexSchemeSurfaceColors.themeSurface
, that was already then replaced with FlexSchemeSurfaceColors.surfaceStyle
, was completely removed in version 2. If you were still using FlexSchemeSurfaceColors.themeSurface
change it to FlexSchemeSurfaceColors.surfaceStyle
.
This is the only breaking non-nullsafety related features. Other changes are breaking only in style and described in the changelog.