Frequently Asked Questions

Below some frequently asked question 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 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 copyWith "modify" it, just like 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?

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 Material 3 Colorscheme, you can get them from FlexColorScheme.

For this advanced 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 data 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 from FlexColorScheme's opinionated 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.

A future version of the Themes Playground application may add these "resets" for a few of the component themes, but you can add them manually to any component theme.

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 buttons)
  • ThemeData.chipTheme
  • ThemeData.inputDecorationTheme
  • ThemeData.tabBarTheme
  • ThemeData.textSelectionTheme
  • 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 are also no longer null, which they are in the vanilla core version:

  • ThemeData.bottomSheetTheme
  • ThemeData.cardTheme
  • ThemeData.checkboxTheme
  • ThemeData.dialogTheme
  • ThemeData.elevatedButtonTheme
  • ThemeData.floatingActionButtonTheme
  • ThemeData.iconTheme
  • ThemeData.navigationBarTheme
  • ThemeData.navigationRailTheme
  • ThemeData.outlinedButtonTheme
  • ThemeData.popupMenuTheme
  • ThemeData.primaryIconTheme
  • ThemeData.radioTheme
  • ThemeData.snackBarTheme
  • ThemeData.switchTheme
  • ThemeData.textButtonTheme
  • 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 a 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 style 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 schemes, why should I use FlexColorScheme?

The purposes of 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 branded and 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 to it matching TabBar.
  • Provide optional support for a true black mode for dark themes.
  • Quickly swap the primary and secondary color definitions, if you want to try your theme the other way around.
  • Theme 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 a more refined and opinionated look on widgets and used 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 can of course be changed by releasing a new major version that break 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?

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, or if you want to keep it less formal and discuss it, post it in the package 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. 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 provide self documenting API guidance on how the data 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.

Sometimes FlexColorScheme not have perfect pub score, why?

Currently, FlexColorScheme has 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 would 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 respect, it basically tells me it would be better to make things worse for you, I just prefer to not do that.

I did open an issue about pana analyzer's current behavior though #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.