Frequently Asked Questions

This chapter contains frequently asked questions and answers about using FlexColorScheme and customizing it beyond what is offered via its API.

In addition to the questions and answers below, you can find more questions, asked by FlexColorScheme users, and answers to them in the GitHub repo discussions section under category Q&A. If you have additional questions concerning FlexColorScheme, theming, Material-3 and ColorScheme in Flutter, you are welcome to post theme there.

Custom Colors?

Can I use custom colors with FlexColorScheme?

Yes, of course.

A FlexColorScheme based theme can like Flutter's standard ColorScheme based theme, be created by specifying all the required color scheme colors. With FlexColorScheme you can also specify only the primary color and get all other colors needed for a complete color scheme computed based the given primary color.

There is a helper class FlexSchemeColor, with a factory called FlexSchemeColor.from, it can create a complete FlexSchemeColor set from incomplete color data. Additionally, its toDark method can create a computed matching dark scheme from a defined light scheme.

These features are useful when you quickly want to test a single color, or maybe only a primary and secondary color for a light theme, and get all other scheme colors computed. When you figure out the colors you want, you can use exactly tuned color definitions and make your custom color schemes from const values instead. Using different ways to create custom color schemes is presented in detail in the tutorial's examples 2, 3 and 4.

You can also use the live version of example 5, the Themes Playground to copy existing color schemes and modify them interactively and copy the code for a theme, either custom one or all the setups you made for a built-in one.

To learn about using the Themes Playground and its more advanced features, please see its own how-to use guide.

Custom Theming?

Can I use custom themes with FlexColorScheme?

Yes, FlexColorScheme creates a ThemeData object. You can use copyWith to modify it, just like with any ThemeData object.

When you make a theme with FlexThemeData.light or dark, it returns a normal Flutter ThemeData object that you can use like any other ThemeData object. From this returned ThemeData you can create a new version with any of its properties and component themes and their properties replaced by using ThemeData's normal copyWith method. You should do this before or when applying it to your application's theme or darkTheme properties.

Custom Component Themes?

Can I use my own custom component theme with FlexColorScheme?

Yes, of course, see previous answer.

Often when you add component themes they need to share ColorScheme color values with the rest of the ThemeData configuration to follow the same style. You may also want to keep some properties FlexColorScheme already defined for you on the component themes it created. Below answer to these questions as well.

Can I use the ColorScheme, FlexColorScheme creates in custom component themes?

Yes

If you need color values that FlexColorScheme has created, maybe some auto calculated colors, typically the blended surface and onColors for your sub-themes, or a computed seed generated Material-3 Colorscheme, you can get the entire ColorScheme from FlexColorScheme.

For this use case, it is recommended to use FlexColorScheme with the factory constructor FlexColorScheme.light and FlexColorScheme.dark, to first create the light and dark FlexColorScheme objects. Then get the ColorScheme they define with its toScheme method, and use this ColorScheme and its colors, as input for your custom component themes.

When you make custom component themes, you often need access to the colors the main ThemeData is using and storing in its colorScheme property. This step gives you that before even creating the ThemeData object from your FlexColorScheme object. You can then pass the ColorScheme you got from toScheme, or just one or some of its color values, along to your methods that define your component theme data.

You can turn your light and FlexColorScheme objects to ThemeData with its toTheme method, and add your sub themes with copyWith to this object in one definition, since they now use the same ColorScheme colors, that the ThemeData created with toTheme will get as well.

You can of course also create the FlexColorScheme ThemeData with the more frequently used ThemeData extensions FlexThemeData.light and dark, and get the ColorScheme object from the ThemeData.colorScheme property. Then use that colorScheme to create your sub-themes that need access to its color values. Finally, use copyWith to create a new ThemeData with your custom sub themes included. This is, however, one extra step and additional ThemeData object compared to the other approach.

How do I reset a component theme back to its Flutter default theme?

When you enable opinionated component themes, FlexColorScheme adds a large number of modified component themes to ThemeData. If you want to reset one or a few of them, back to their Flutter SDK defaults, use copyWith to add a default constructor instance of the component theme in question to the ThemeData object that FlexColorScheme returns.

This will completely override the component theme FlexColorScheme produced with a default one, where all the properties are null. Flutter will then use default theming for the component theme in question.

For example, if you want to restore the look of the ElevatedButton in M2 mode, from FlexColorScheme's opinionated M2 design, you could do this for the light theme:

final ThemeData lightTheme = FlexThemeData.light(
  subThemesData: const FlexSubThemesData(),
).copyWith( 
  elevatedButtonTheme: const ElevatedButtonThemeData(),
);

Remember to do the same for your dark theme as well.

How do I modify the component themes with custom features?

If you want to make modifications to a component theme that FlexColorScheme already created, and you want to keep some values it defined, the steps are a bit more involved than resetting it back to default values.

To only override a few property values in a component theme created by FlexColorScheme, you will need to first create the FlexColorScheme based ThemeData object. Use the component theme from it that you want to add a modified copy of as input to the new ThemeData. In such a case you might as well use FlexThemeData.light and dark API, since there is no win in the steps by first creating the FlexColorScheme object.

If you are not opting in on the opinionated component themes, then the component themes that get created and modified by FlexColorScheme core are:

• ThemeData.appBarTheme
• ThemeData.bottomAppBarTheme
• ThemeData.bottomNavigationBarTheme
• ThemeData.buttonTheme (for the legacy deprecated/removed buttons)
• ThemeData.chipTheme
• ThemeData.inputDecorationTheme
• ThemeData.tabBarTheme
• ThemeData.tooltipTheme

The changes made in the vanilla FlexColorScheme based ThemeData component themes are fairly small, but the above component themes are not null, like they are by default in Flutter SDK. You can read more about these changes FlexColorScheme makes in the core defaults chapter.

When you opt in on using the opinionated component themes, the above component themes are typically further modified. Additionally, the following component themes may also no longer be null, which they are in the vanilla core version:

• ThemeData.bottomSheetTheme
• ThemeData.cardTheme
• ThemeData.checkboxTheme
• ThemeData.dialogTheme
• ThemeData.drawerTheme
• ThemeData.dropdownMenuTheme
• ThemeData.elevatedButtonTheme
• ThemeData.filledButtonTheme
• ThemeData.floatingActionButtonTheme
• ThemeData.iconButtonTheme
• ThemeData.menuBarTheme
• ThemeData.menuButtonTheme
• ThemeData.menuTheme
• ThemeData.navigationBarTheme
• ThemeData.navigationRailTheme
• ThemeData.outlinedButtonTheme
• ThemeData.popupMenuTheme
• ThemeData.primaryIconTheme
• ThemeData.radioTheme
• ThemeData.segmentedButtonTheme
• ThemeData.sliderTheme
• ThemeData.snackBarTheme
• ThemeData.switchTheme
• ThemeData.textButtonTheme
• ThemeData.textSelectionTheme
• ThemeData.timePickerTheme
• ThemeData.toggleButtonsTheme

If you want to add custom component themes and keep the already existing modified properties in ThemeData created by FlexColorScheme intact, you cannot use just a copyWith using a component theme constructor. You have to use the component theme instance from the ThemeData created by FlexColorScheme, and a copyWith on it. Then assign it to the component theme with a copyWith to the new ThemeData, with the modified properties.

This is the same way that you would "modify" ThemeData when you create scoped ThemeData inside your app, and want it to fully inherit the parent's Theme, but with a few properties modified in some component theme only. In the Flutter documentation, this is shown in Cookbook > Design > Themes.

This sounds more complicated than it is. To make it easier to follow, here is an example of what it looks like. Say you want to modify shadow color of the appBarTheme in ThemeData, but you also want to keep all the other theme changes FlexColorScheme has introduced to it, like e.g. using surface color with a blend of primary as its background color, if you had chosen that mode for the AppBar theme. You can then add your shadow color to it like this:

class MyApp extends StatelessWidget {
    @override
    Widget build(BuildContext context) {
    final ThemeData lightTheme = 
      FlexThemeData.light(scheme: FlexScheme.mandyRed);
    return MaterialApp(
      title: 'Flutter Demo',
      theme: lightTheme.copyWith(appBarTheme: lightTheme.appBarTheme.copyWith(
           shadowColor: const Color(0xFF2D0606))),
      themeMode: ThemeMode.light,
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

In the Discussions section of the FlexColorScheme repo you can find a few questions and examples on how to do this. In this first question and answer the above AppBarTheme example is discussed further here. A similar question regarding the background color of bottomSheetTheme is discussed here. In the third case, a similar case for button themes is discussed. It is a bit more complicated due to different structure of the button themes, where all their styles are tucked into a common single style property made of ButtonStyle. You can find this example here.

One additional possibility when creating totally custom component themes is to utilize the static helper functions in the FlexSubThemes class. FlexColorScheme uses them internally to create its opinionated component themes. You can find their API documentation here.

They offer simplified APIs for setting and using more involved features in standard SDK sub-theme. You can also use them to check out how a particular design is implemented, if you e.g. want to replicate it in a standard Flutter SDK sub-theme.

You can also use these component theming functions to make custom sub-themes, and complement them with copyWith values for properties they do not provide. Please note that the FlexSubThemes static helper functions are not meant to provide all properties for all existing component themes. They only cover the properties and shortcut features needed by FlexColorScheme. When using FlexColorScheme, you use them under the hood via the FlexSubThemesData configuration class, passed in to FlexColorScheme.subThemesData property, as a convenient way to enable and configure them.

If I don't use the built-in color schemes, why should I use FlexColorScheme?

The purpose of the FlexColorScheme package is to:

• Address some minor gaps in Flutter's standard ThemeData creation methods and make all SDK Widgets, old and new, use the specified ColorScheme in a consistent manner.
• Enable easy switching among multiple color schemes in an app.
• Provide an easy way to make themes with primary color-blended backgrounds and surfaces. Be able to easily vary the blend level for different surfaces.
• Provide a quick toggle for different AppBar styles, without the need to manually make a custom theme for it every time, including matching TabBar.
• Provide optional support for a true black mode for dark themes.
• Quickly swap the primary and secondary color definitions, to try your theme the other way around.
• Style the Android System navigation bar to match your app theme, and make it partially or totally transparent.
• Provide seed color generated Material-3 color schemes, with more configuration and custom tuning possibilities than what is offered directly in Flutter SDK.
• With default settings, FlexColorScheme avoids making major changes to the component theme definitions, but in a few cases it is needed to fix things and to make some minor design changes. In the default produced ThemeData the changes are as few and subtle as possible, leaving the task of component theming up to you. However, when you opt in on using its component themes, you get more refined and opinionated styled widgets and TextTheme. The defaults for the component themes are inspired by the new Material-3 guide. Following it when it can easily be accomplished by using the still mostly Material-2 based more limited theming capabilities in Flutter. Full support for Material-3 widgets and themes is coming to Flutter soon. The progress can be followed here.
• FlexColorScheme also provides a way to make computed multi-toned based themes, from just a single or a few light scheme colors as input. Even its dark scheme counterpart can be made from this single color definition. This is similar in concept to ColorScheme.fromSeed in Material-2. It has been available since version 1.0 of FlexColorScheme. It is a simpler form of computational ColorScheme generation, not as advanced ColorScheme.fromSeed, but it comes with fewer color surprises.
• FlexColorScheme defines the full color set in the new Material-3 ColorSchemes and does not leave most of its values repeating the same color by many properties.
• Enable you to click around and play with your theme design using the Themes Playground and copy-paste the setup into your app.

If you like the above features, then FlexColorScheme may fit your theming requirements, even if you do not use any of its built-in color schemes.

Can we change this existing scheme's colors?

No, current predefined schemes will not be changed lightly. Changing them would be a breaking change to the package version promise. The scheme colors could of course, potentially be changed by releasing a new major version, that breaks past scheme color definitions. At the moment, there are no plans to ever add breaking releases to just change a predefined scheme's color(s). Such changes are only done when so required by changes in Flutter's color design. Version 5 is the first release to include such changes since the entire ColorScheme changed, as did the color design system via Material-3.

All current color definition values are also included in the package tests. A failed color value test is considered a breaking change. So a new color value for a past existing color is a major breaking change and requires a new major release.

Can we add my ColorScheme suggestion to FlexColorScheme?

Maybe. To keep things interesting, there will from time to time be new color schemes added to the package. If you have a beautiful color scheme with matching light and dark theme mode colors that you think would be perfect to include, then please post a suggestion as a GitHub issue. Alternatively, if you want to keep it less formal and discuss it, post it in discussions.

No promise is made about its eventual inclusion, but if it is a nice, unique, and overall a pretty color scheme, it will likely be included. Coming up with nice color schemes is trickier than it seems, suggestions and contributions to new ones are very welcome.

Can I use different built-in color schemes for my light and dark themes?

Yes, this is possible. The Themes Playground does not support this, but the API does. Simply use different FlexScheme enum values for the light and dark FlexThemeData.light and FlexThemeData.dark factories' scheme property. If the colors used by the selected schemes are a bit related, this can be used to create nice and unique light and dark combinations of the predefined schemes.

By using the colors property you could even apply a FlexSchemeColor that has data that was designed for a light theme, to the FlexThemeData.dark factory, and wise versa. For example, using the FlexThemeData.dark factory, you could to its colors property assign the FlexSchemeColors from FlexColor.schemes[FlexScheme.mandyRed].light that are designed and intended to be used with the light mode factory.

The results will typically not be very useful or pretty. The rationale for the slightly involved data structure, is to keep it flexible, but at the same time to provide self-documenting API guidance on how it was designed to be used and consumed.

The scheme property prevents using the light scheme colors for the dark factory and wise versa. It can however be done if so desired by using the colors property as explained above. The colors property is always needed and used when you make custom color schemes using the FlexThemeData.light and FlexThemeData.dark factories.

If you are making custom color schemes and would just like to re-use one or two color values from FlexColorScheme in a custom scheme, then all its color values are also conveniently available as const Color values. See FlexColor API docs for full details.

Why are some sub-theme properties in the main class and not it FlexSubThemesData?

TLDR: Legacy!

When development of FCS was started, it was mostly used for colors and to fix a few glaring issues that always needed tuning in Flutter themes. All such properties were then included in the main class.

This concerns mostly theming related to the AppBar, TabBar and Tooltips. When the subThemesData property was added to support more extensive configuration of a lot of component sub-themes via FlexSubThemesData, we did not want to break past API and kept them there. Today this is a bit inconsistent and may well be considered technical debt. We may later gradually deprecate the direct none color related properties in the main class and move them to FlexSubThemesData, in a none-breaking manner for a few releases.

Sometimes FlexColorScheme does not have a perfect pub score, why not?

FlexColorScheme aims to have a perfect pub score, but it may at times be lower, typically 130/140 score. This happens when it is being nice and documents self-deprecated members and references them in doc comments. It may also internally use self-deprecated members to provide a nicer transition using past deprecated members as fallbacks. This is done in cases where it is possible and makes sense to not unnecessarily break things, while transition you to newer APIs.

In situations like this, if FlexColorScheme were to document things more poorly, and not be nice with API transitions, but prefer to just totally break things, it would have a perfect pub score. The current pana analyzer used by pub.dev is a bit peculiar in this case. It basically says it would be better to make things worse for you, we prefer to not do that.

An issue about pana analyzer's current behavior was opened #1055. A change PR #1057 to allow using self-deprecated members without a score penalty was in the works, but got closed without being merged.