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 8.2

No migration needed from version 8.1. You may want to check the changelog for info on some new features and minor changes.

Migrating to version 8.1

No migration needed from version 8.0. You may want to check the changelog for info on some new features and minor changes.

Migrating to version 8.0

The most critical changes to migrate from FlexColorScheme V7 to V8 are listed below. For a full list of all breaking changes, see PACKAGE CHANGES and the BREAKING CHANGES part in the pub.dev CHANGELOG.

• The flag useMaterial3 now defaults to true in FlexColorScheme and FlexThemeData constructors. Set it to false to explicitly use Material-2 theming. It defaulted to true before. Material-2 is still fully supported in FCS v8 and Flutter v3.24, but will eventually be deprecated in Flutter, when that happens, it will also happen in FCS.

• The FlexSubThemesData properties interactionEffects, tintedDisabledControls, defaultUseM2StyleDividerInM3 and blendOnColors now all default to false. In previous versions they defaulted to true. If you before had not explicitly turned these properties false, they were all true by default. To get the same result as before in FCS V8, you now have to set these properties to true. This change was made to have fewer opinionated defaults in FCS to align it more with Flutter SDK default styles.

• The FlexSubThemesData property navigationRailLabelType no default to NavigationRailLabelType.none. To get the same result as before by default, you will need to set it to NavigationRailLabelType.all. This change was made to have fewer opinionated defaults in FCS to align it more with Flutter SDK default styles. The Playground defaults it to NavigationRailLabelType.all by adding this by default to new default themes.

• Since ColorScheme.background color was deprecated in Flutter 3.22.0 we can no longer use it as a part of surface blends and its modes. For example, when surfaceMode is set to FlexSurfaceMode.highBackgroundLowScaffold it now uses surface and dialog blends set to 2x instead of 1x, so that it represents the "high background" style as before, but done via surface color. Without this breaking change, this mode would produce the same result as FlexSurfaceMode.levelSurfacesLowScaffold and be redundant.

  • NOTE: You may want to check your surface mode and blends to see that they still look as you want them to, as they may have changed slightly depending on your configuration. We have tried to keep required changes subtle, you may not notice any difference, but it is good to check. These changes we forced by Flutter 3.22.0 deprecation of ColorScheme colors background, onBackground and surfaceVariant.

This major release has many breaking changes forced via breaking changes in Flutter 3.22.0. Due to this, the release also uses this opportunity to clean up APIs with opinionated defaults, like the ones mentioned above. There are additional smaller and more subtle changes in defaults values, that align FCS to use the same color defaults from the new ColorScheme colors, that Flutter started using in version 3.22.0 as well. You can find all the details below in the BREAKING CHANGES part in the pub.dev CHANGELOG.

Migrating to version 7.3

No migration needed from version 7.2. You may want to check the changelog for info on some minor style changes.

Migrating to version 7.2

No migration needed from version 7.1. You may want to check the changelog for info on some minor default and style breaking changes, especially when using Material-2.

Migrating to version 7.1

No migration needed from version 7.0. Just upgrade Flutter to min version 3.10.0 and FlexColorScheme to version 7.1.0 or higher.

Migrating to Version 7.0

To migrate from version 6 to version 7 is quite easy. Typically, you only need to upgrade to the latest version of the package. If you have not used a few low-level features, you should not run into any breaking APIs, your app should build fine. There are a few minor breaking APIs, and some APIs that change past default styles. For a full breakdown of all changes, you can review the development change logs from version 6.1.2, to 7.0.0-dev.3, listed below:

• Changes from 6.1.2 to 7.0.0-dev.1

• Changes from 7.0.0-dev.1 to 7.0.0-dev.2

• Changes from 7.0.0-dev.2 to 7.0.0-dev.3 (final beta)

• Changes from 7.0.0-dev.3 to 7.0.0

  • Package: Only tests and documentation additions and updates.
  • Playground: Label and layout corrections.

The breaking APIs and breakage with past styles are listed below. If you come across something that does not look exactly as in version 6, especially when using M3 mode, you can find the explanation and rationale for the change below.

API breaking

• In FlexSubThemes the floatingActionButtonTheme and timePickerTheme now require the colorScheme, previously it was optional in both. Unless you have used FlexSubThemes.floatingActionButtonTheme or FlexSubThemes.timePickerTheme directly as helpers to make custom component themes with them, and not as typically used via FlexSubThemesData, you will not notice this breaking API change.

API change, breaking defaults

• The unselectedIsColored parameters in FlexSubThemes functions switchTheme, checkboxTheme and radioTheme were changed to be nullable and to default to false if not defined. Previously, they were not nullable and defaulted to true. If you have not used these FlexSubThemes functions directly, typically they are not used directly, then this change has no impact on resulting themes, since FlexSubThemedata.unselectedToggleIsColored defaulted to false earlier as well, and set these sub-theme values to false by default, or true when so defined.

• The FlexSubThemesData property useTextTheme, is now nullable and defaults to null. Previously it was not nullable and defaulted to false. As before, this boolean toggle determines if the Material-3 TextTheme and Typography are used.

  • When opted in on using FCS sub-themes, this flag controls if text theme uses the new Material Typography.material2021.
  • If not defined, and ThemeData.useMaterial3 is true, then useTextTheme defaults to true and Typography.material2021 is used.
  • If ThemeData.useMaterial3 is false, then useTextTheme defaults to false, and Typography.material2018 is used.
  • This toggle works as a quick override setting for using Typography.material2021 in Material-2 mode, and for using Typography.material2018 in Material-3 mode.
  • As before, when using FlexColorScheme and ThemeData.useMaterial3 is false and sub themes are not used, the default typography is Typography.material2018. Note that if FlexColorScheme is not used at all, and your ThemeData has ThemeData.useMaterial3 set to false, then Flutter defaults to using obsolete Typography.material2014. In such a case, consider defining your typography manually to Typography.material2018 or why not even Typography.material2021.
  • If you specify a custom typography for FlexColorScheme or FlexThemeData, the useTextTheme property has no impact on used typography at all.

• FlexSubThemes.blendTextTheme defaults to false.
  In FCS before version 7, the default for blendTextTheme in FlexSubThemes was true, and blended text themes were used by default. Going forward if you want it, and also if you had not defined it earlier, and do not want to break your apps past style, set blendTextTheme to true.

Breaking label value

• The FlexColor.materialBaselineName name string was changed from 'M3 baseline' to 'Material-3 purple'.

• The FlexColor.materialBaselineDescription description string was changed from 'Material guide 3 baseline based theme' to 'Material-3 guide and default purple theme'.

Style breaking

The breaking styles below refer to changes where version 7 modifies how the defaults look compared to version 6.1. Most changes impact only M3 mode. They were done to align the FCS M3 mode defaults with Flutter's default M3 styles. Flutter 3.7 improved and/or added M3 support to most Material widgets. FCS needed to become more aligned with expected defaults when enabling M3 and also when opting in on component themes in M3 mode.

• Drawer uses the correct M3 specification width 360 dp, as default width in M3 mode. In M2-mode it still uses the old default, 304 dp. In version 3.7, Flutter has a bug that still keeps the Drawer at 304 dp in M3 mode. The 360 dp width is too wide for small phones that typically only have 360 dp usable width pixels. You can read more about the Drawer width in Flutter issue #123380, that also contains a discussion and analysis of the topic. It remains to be seen what the Google Material team will reply to the issue. In either case, 360 dp is too wide for many phones. You may want to adjust it. You can set the width to whatever you want it to be with:

  subThemesData: const FlexSubThemesData(
     drawerWidth: 320.0, // Or use 304.0 for same value as before and in Flutter M2 default.
  ),

• Card elevation default 1 dp.
  The Card opinionated sub-theme now defaults to null elevation, resulting in same default of 1 dp elevation as Flutter SDK in both M2 and M3 mode. Previously, FCS defaulted to elevation 0 dp on Cards when opting in on sub-themes.

• ColorScheme.outline and ColorScheme.outlineVariant.
  The FCS built-in computed none seeded values for ColorScheme.outline and ColorScheme.outlineVariant were modified. The new values are more in line with what you get with the M3 default seed algorithm, but plain gray-scale variants of them without any primary color blend. Technically light mode color for outline was changed from 30% lighten of light mode onBackground color to 45%, and outlineVariant from 60% lighten of onBackground to 75%. Likewise for the dark mode, but with darkening of the onBackground with the same percentage changes. The new values match the M3 design intent better.

• Version 7 introduces custom colors for FlexColor.lightSurfaceVariant and FlexColor.darkSurfaceVariant colors that are used when making none-seeded ColorSchemes. The colors are plain, not tinted light and grays, matching the gray level of the tinted versions you get with seed-generated M3 colors. The colors are used as defaults for light and dark surfaceVariant color in none-seeded versions of generated FlexColorScheme color schemes. In previous versions surfaceVariant was just white and black in light and dark theme mode. To be able to better match the M3 color system, without using seed generation, this surface color should not be just white or black. The new surfaceVariant corrects this past design to improve compatibility with the M3 color system when not using seed generated color schemes.

• Changed the FCS default NavigationBar height from 62 dp to 80 dp. The 80 dp height is also the M3 spec default height for a Material-3 NavigationBar in Flutter. This makes the FCS default NavigationBar theme less opinionated compared to M3 spec. The FCS default background color is now using surfaceVariant in M2 mode, and defaults in M3 to its spec surface with elevation tint. The FCS M2 surfaceVariant default makes it look a bit more like the M3 mode surface with elevation tint. Especially if you use a seed-generated ColorScheme or FCS surface blends. This makes the FCS difference in style between M2 and M3 mode less than before. Since M2 does not support surface tint, it cannot match it exactly.

• All component themes have null properties in M3 mode. When enabling Material-3 and not enabling FCS sub-themes, and if no direct properties in FlexColorScheme raw constructor, or its light and dark factories are set in a way that requires creating a sub-theme to deliver the result, FlexColorScheme no longer creates any component sub-themes with none-null properties in Material-3 mode. In previous versions, it did so in a few cases. This is no longer required to deliver a nice starting point M3 theme, thanks to M3 now being almost fully supported in Flutter 3.7. When using FlexColorScheme with useMaterial3 set to true and its other properties at default values, and not enabling sub-themes, all component sub-themes will have null by default properties in FCS, just like in plain ThemeData. When using Material-2, FlexColorScheme as before even when not enabling sub-themes, still creates core component themes listed under core default in the documentation. This is done for FCS legacy reasons, and to be able to deliver the default slightly opinionated M2 style it had before component sub-themes were a part of its offering.
  Impact: The impact of this style breaking change is only visible on the Material-2 type BottomNavigationBar in dark mode. When using the M3 mode, its dark mode icons have changed to the Flutter default style. When you opt in on FCS sub-themes in the M3 mode, it gets the same icon color as before, like it still gets in the M2 FCS style, with or without sub-themes enabled. Since the BottomNavigationBar is a Material-2 component, this should be less relevant in the M3 mode. With component themes on, it looks as before.
  Note: Later when theme.scaffoldBackgroundColor and maybe also some other colors in current ThemeData are deprecated, FlexColorscheme will need to set those colors in their own sub-theme, also in M3 mode to be able to continue to deliver e.g. surface blends that impacts the scaffold background color separately from ColorScheme colors. Currently, it does this via theme.scaffoldBackgroundColor without using a component theme.

• The SnackBar action button defaults to inversePrimary.
  The SnackBar theming got property snackBarActionSchemeColor in FlexSubThemes. It defaults to M3 default inversePrimary. Earlier FCS used its foreground color with alpha 0xDD for the action button text color. Flutter's M2 defaults are poor designs and not very usable, but new Flutter M3 defaults are fine. As before, FCS uses a custom default style to fix M2 when using sub-themes. The M3 mode default is also opinionated, to make it match M3 defaults, set FlexSubThemes.snackBarBackgroundSchemeColor to SchemeColor.inverseSurface. By default, it uses the same style as its opinionated M2 style, which is onSurface alpha blended with primary and opacity, both alpha blend and opacity are different in light and dark theme mode. This was kept as the default also in M3 mode, so it can be used as an option there as well. If you want the pure M3 style, select inverseSurface instead. This part of the style is same as before so not style breaking, only SnackBar action button got a new default text color, that can be themed to any ColorScheme based color.

• Tinted TextTheme was made less obviously tinted. M3-seeded ColorSchemes brings color tint to themes, if then also using tinted text, via the optional tinted TextTheme, is becomes too much. It is now more subtle and more usable also with seeded ColorSchemes. The changes are:

  • TextTheme light mode:
    • Hi opacity style: Blend 30% -> 20%, Opacity 75% -> 85%
    • Medium opacity style: Blend 26% -> 20%, Opacity 95% -> 96%
    • No opacity style: Unchanged.
  • TextTheme dark mode:
    • Hi opacity style: Blend 25% -> 15%, Opacity 80% -> 92%
    • Medium opacity style: Blend 20% -> 12%
    • No opacity style: Blend 18% -> 15%

• FlexColorScheme's own algorithm to compute light and dark theme container colors from their main colors, was modified to align better with expectation by the M3 color system. The changes are:

  • In light theme mode:
    • Primary container: primary.blend(Colors.white, 60) -> primary.lighten(20).blend(Colors.white, 60)
    • Secondary container: secondary.blend(Colors.white, 60) -> secondary.brighten(14).blend(Colors.white, 50)
    • Tertiary container: tertiary.blend(Colors.white, 80) -> tertiary.brighten(18).blend(Colors.white, 50)
  • In dark theme mode:
    • Primary container: primary.blend(Colors.black, 60) -> primary.darken(5).blend(Colors.black, 55)
    • Secondary container: secondary.blend(Colors.black, 60) -> secondary.darken(25).blend(Colors.black, 50)
    • Tertiary container: tertiary?.blend(Colors.black, 80) -> tertiary.darken(15).blend(Colors.black, 60)

• The border radius on containers for ToolTip, PopupMenuButton, DropdownMenu and Menu no longer follow the global override for defaultRadius. These items should generally not be themed together with a large general radius override. They can still be modified individually.

• The boolean FlexSubThemesData.interactionEffects no longer modifies ThemeData.disabledColor. This part of the control is now instead controlled separately by FlexSubThemesData.tintedDisabledControls.

• The boolean FlexSubThemesData.interactionEffects now correctly control if color-tinted interaction effects for hover, focus, highlight, pressed and splash are used. The setting affects both M2 and M3 mode, and all in FCS covered component themes, to the extent that the Flutter SDK supports changing their interaction effects. All components have new tinted interaction effects that are used when setting this property to true. When it is false, all components use Flutter SDK default gray styles.

• The boolean FlexSubThemesData.tintedDisabledControls now correctly control if color-tinted disabled widgets are used. The setting affects both M2 and M3 mode, and all in FCS covered component themes, to the extent that the Flutter SDK supports changing their disabled color. All components have new tinted disabled styles that are used when setting this property to true. When it is false, all components use Flutter SDK default disabled gray styles.

• In Material-2 mode the InputDecorator's border radius default value was changed from 16 to 10, to be less rounded by default.

• The ToggleButtons theme has a slightly changed style in both M2 and M3 mode. It now also correctly reacts to FlexSubThemesData.interactionEffects and FlexSubThemesData.tintedDisabledControls. The slight change of past theme was needed to support this. The new theme has better interactions colors and match what you get on OutlinedButton and FilledButton.

• The FlexColorScheme TimePicker dialog style in M3 mode was changed. It is now styled closer to the Material-3 specification. It is also closer to correct M3 style than Flutter is in version 3.7. When Flutter fully supports TimePicker M3 theming in the stable channel, FCS will use its native styling as its default too.

• Changed FlexColorScheme default BottomAppBar color to be colorScheme.surface, same as Flutter default. Previously FlexColorScheme used colorScheme.background color as an opinionated default. The change is minor, and in many designs the color values are the same.

• Previously existing native Material-3 color schemes, materialBaseline, verdunHemlock and dellGenoa were changed to use Material-3 error colors, also in Material-2 mode and when not using seed colors.

• Changed FlexColorScheme.bottomAppBarElevation to be nullable. In M2 mode if is null, it follows defined appBarElevation as before. In M3, it is kept null in order to default to M3's default elevation of 3, so that BottomAppBar get elevation tint by default. Not considered style breaking because BottomAppBar was not supported before in M3.

• When making seed generated ColorScheme with a custom surfaceTint color. This tint color is now also used as seed-key for the neutral and neutral variant tonal palettes. Flutter SDK can only use primary color as seed-key for the neutral colors. This limitation in Flutter makes using a custom surfaceTint in seeded ColorSchemes less usable with often unappealing results. This happens because the custom tint color then differs from the slight primary tint that is hard coded into Flutter's seeded neutral colors used for surfaces and backgrounds, and the colors may clash. In FlexColorScheme the custom tint color is automatically also used to slightly tint the neutral colors used for surfaces and backgrounds in the seed-generated ColorScheme. The same color is then also used as ColorScheme.surfaceTint color. This makes the custom elevation tint color match the custom seed-tinted surface and background colors. This feature is enabled by the FlexSeedScheme package starting from version 1.2.0-dev.1. When using a custom surfaceTint color, the same color is also used as the surface alpha blend color, when using SurfaceMode and blendLevel to adjust surface color with or without using seed generated ColorScheme. Ensuring that neutral seed tint, elevation and surface blend color always match, as they should.

• Changed, or one could call it fixed SnackBarTheme action and close icon colors. They are now also themed automatically to fit on selected SnackBar color.

• The InputDecorationTheme, can now be configured to match Material-3 for critical styles if so desired. It uses a few opinionated values that give it a slightly different style by default. It can be configured to match M3 defaults if so desired. FCS does one opinionated adjustment to error border and suffix icon. It keeps them error colored on unfocused-hovered error state, instead of onErrorContainer. The M3 default looks odd. This FCS change is considered an opinionated M3 style fix in FCS. The M3 default of setting unfocused hovered error floating label also to onErrorContainer, is also keeping FCS own past style error.withAlpha(0xA7), which looks more refined. There is currently no way to set these settings back to the M3 default style within FCS. You can of course as always adjust them and anything with copyWith on produced ThemeData if needed.

• Added theming for TimePicker that corrects Flutter SDK issue https://github.com/flutter/flutter/issues/118657 when using FCS component sub-themes.

• Made tabBarStyle in FlexColorScheme, FlexColorScheme.light, FlexColorScheme.dark, FlexThemeData.light and FlexThemeData.dark nullable and null by default. In M2 mode tabBarStyle defaults to FlexTabBarStyle.forAppBar as before. However, in M3 mode, if not defined, it defaults to FlexTabBarStyle.flutterDefault, producing a style matching M3 default TabBar.

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 the 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 compared to Material-2. This may surprise users of previous FlexColorScheme versions that had opted in on using 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
  ),

Other style changes

There are some other minor style changes to default values when opting in on Material. Please see the changelog for a complete list.

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 as close as possible, style aligned with past styles, while also keeping them inline with 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 in FlexColorScheme.light and FlexSchemeData.light.
• Removed property: surfaceStyle in FlexColorScheme.dark and FlexSchemeData.dark.
• Removed: enum FlexSurface, that only surfaceStyle was using.
• Removed: factory FlexSchemeSurfaceColors.from that was used to create surface using the surfaceStyle. The factory FlexSchemeSurfaceColors.blend replaced it in version 4.0.0 already, when using surfaceMode and blendLevel.

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. The right 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 properties primaryVariant and secondaryVariant
• or defined and used them via custom FlexSchemeColors, in the colors property in FlexColorScheme.

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 versions 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.