rydmike/flex_color_scheme_docsLight logoFlexColorScheme

Core Defaults

This chapter describes the ThemeData modifications FlexColorScheme core does when you use it without opting in on the opinionated component themes.

FlexColorScheme does not use the ThemeData.from factory with a passed in ColorScheme to make its ThemeData object. It uses the ThemeData factory directly, with many additional custom theming tweaks.

It of course defines a ColorScheme that it uses in its ThemeData. FlexColorScheme uses color calculations for the primary color branded/blended surfaces, and for the lazy schemes that do not specify all colors in a color scheme. It utilizes the Material Color Utilities from the Google Material theme that Flutter SDK also uses to make key colors seed-generated computational color schemes. It extends the new M3 CorePalette in the Material Color Utilities to be able to tweak the ColorScheme generation parameters in it. It also uses its own custom mid-layer Scheme implementation, with customizable Tones to ColorScheme mapping.

Most other things it does are more basic, just more moving parts. However, when just using the core, and not opting in on additional component themes, it uses fewer component theme customizations. The core setup however, also creates some component themes. They are listed further below.

Design Goals

Flutter's default Theme and its ThemeData use a design where all the component theme's in the default ThemeData have properties that are all null. It is always the widget component that defines the default behavior and style when its theme and its properties are undefined. The widget colors for such cases are then typically defined by ThemeData.colorScheme.

This Flutter theming design goal is described in this document. It is partially implemented, but there are still components in Flutter remaining that do not adhere to this design, and there are also many color properties still remaining in ThemeData.

FlexColorScheme assigns its defined and computed colors to the ThemeData.colorScheme to ensure that its colors are applied to all widgets that adhere to this newer standard. Then it also defines all still existing legacy direct colors in ThemeData, that some Flutter Widgets still use. These ThemeData colors are all set to use ColorScheme appropriate colors, or from it derived colors. Thanks to this, there are not any built-in Widgets in Flutter that do not get color themed by FlexColorScheme. As we can see in Roads to ThemeData, this is not the case with Flutter's own ColorScheme-based theming methods, or any of its theming methods. You always have to adjust ThemeData a bit manually as well to get there. With FlexColorScheme this is not the case.

The ThemeData created by core FlexColorScheme tries to not create and modify component themes when it does not have to. However, to meet its own design goals, FlexColorScheme still has to create a few sub-themes and set some of their properties. In some rare cases, this is done to correct theming issues in Flutter SDK, but mostly it is done to reach its own design goals. Below is a list of all the component themes it creates and properties that you can currently expect to have none-null values in them. These component themes and their properties would otherwise be null when just using default ThemeData() or ThemeData.from() factories, if they did not specify any component themes.

Even if some component themes are currently not null, and have some none null properties in FlexColorScheme based ThemeData, you should still always use null fallback values when you access ThemeData sub-themes and their properties in Theme.of(context) that are null in default ThemeData, or any of its component themes.

For example, when using the AppBar's theme data, don't just use:

final Color aColor = Theme.of(context).appBarTheme.backgroundColor;

It should not be considered safe to access properties like it without using null fallbacks. Instead, do something similar to this:

final Color aColor = Theme.of(context)?.appBarTheme?.backgroundColor ??
  Theme.of(context).colorScheme.primary;

FlexColorScheme will try to not change past creation of its none null sub-themes. However, changes to these implementation details are only considered breaking if they produce a theme that is visibly different from past behavior.

Flutter SDK may also change some of its implementation details of ThemeData. Take, for example, the Chip case, if it is modified to fix its dark theme bug, then FlexColorScheme might have no reason for its own fix. In cases where Flutter defaults move in a direction that makes a custom definition for it no longer needed in FlexColorScheme, such core sub-theme definitions may be removed from its core component themes.

One past such case was the floatingActionButtonTheme sub-theme that FlexColorScheme created in earlier versions. The used sub-theme did not change Flutter's default behavior. However, in some older versions of Flutter there was a deprecation warning if the sub-theme was not defined. It was later observed that the Flutter SDK default and FlexColorScheme sub-theme agreed 100% on the design. This sub-theme definition was thus no longer needed and was removed starting from FlexColorScheme version 2.0.0-nullsafety.2. Another similar change was the deprecation of ThemeData.accentColor.

Core Component Themes

Here are all the component themes that core FlexColorScheme currently defines:

  • AppBarTheme in ThemeData.appBarTheme is NOT null. The actual values are defined to match the offered convenience theming options for the AppBar. The property values depend on made configuration choices.

    • backgroundColor: Depends on chosen appBarStyle.
    • foregroundColor: Black if the brightness of backgroundColor is light otherwise white.
    • iconTheme: Not null, defines:
      • color: : Depends on chosen appBarStyle.
    • actionsIconTheme: Not null, defines:
      • color: : Depends on chosen appBarStyle.
    • elevation: As defined, default is 0
    • systemOverlayStyle: A custom SystemUiOverlayStyle is defined
    • backwardsCompatibility: false

  • BottomAppBarTheme in ThemeData.bottomAppBarTheme is NOT null.

    • Color: colorScheme.background
    • elevation: As defined, if undefined default is 3 in M3 and 8 in M2

  • InputDecorationTheme in ThemeData.inputDecorationTheme is NOT null.

    • filled: true
    • fillColor: dark ? primary.withOpacity(0.06) : primary.withOpacity(0.35)

  • ButtonThemeData in ThemeData.buttonTheme is NOT null.

    • colorScheme: colorScheme
    • textTheme: ButtonTextTheme.primary
    • materialTapTargetSize: MaterialTapTargetSize.shrinkWrap
    • padding: EdgeInsets.symmetric(horizontal: 16)

  • ChipThemeData in ThemeData.chipTheme is NOT null. It was originally defined to fix issue #65663 and uses ChipThemeData.fromDefaults to set:

    • secondaryColor: colorScheme.primary
    • brightness: colorScheme.brightness
    • labelStyle: textTheme.bodyText1

    The issue has been resolved, but the same ChipThemeData is still in use for backward style compatibility.

  • TabBarTheme in ThemeData.tabBarTheme is NOT null. Its colors depend on if a theme appropriate for current active AppBar background color (default), or one for background and surface color usage is selected. It sets:

    • indicatorSize: TabBarIndicatorSize.tab
    • labelStyle: TextTheme().button
    • labelColor: Depends on selected and targeted main usage.
    • unselectedLabelColor: Depends on selected and targeted main usage.

  • BottomNavigationBarThemeData in ThemeData.bottomNavigationBarTheme is NOT null.

    • selectedIconTheme: Not null, defines:
      • color: colorScheme.primary
    • selectedItemColor: colorScheme.primary

  • TooltipThemeData in ThemeData.tooltipTheme is NOT null. This theme is modified to address issue #71429 and to also enable a toggle that inverts the tooltip colors, which is a style often used on Windows desktops. The toggle can e.g. be used to change the style depending on the current platform. The font size issue and padding issues for multi line tooltips have been solved. Past core themes used to handle font and padding part have been removed starting version 6.1.0, when using default Tooltip styles. Effective style remains very similar but is handled by Flutter SDK defaults.

    The remaining used logic and core theme default are defined as:

    • tooltipsMatchBackground: false
      • Dark theme: text: black
      • light theme: text: white
      • Any other theming is just Tooltip widget defaults.
    • tooltipsMatchBackground: true

      • Dark theme:

        • text: white
        • background: Color(0xED444444)

      • light theme:

        • text: black
        • background: Color(0xF0FCFCFC)

      • corner radius: 4 dp

      • Border: Yes, dividerColor

      • Desktop OS (macOS, Linux, Windows)

        • Font size : 12 dp

      • Mobile OS (iOS, Android, Fuchsia)

        • Font size : 14 dp

Core ThemeData Customizations

In addition to the primary color-branded surfaces, full-shaded schemes from just one primary color, true black and AppBar convenience tricks. The returned ThemeData contains some opinionated modifications and theme modifications compared to what you get if you would just use the standard ThemeData.from a ColorScheme.

You can still of course override the returned ThemeData with your own theme modifications and additions, by using the copyWith method on the resulting ThemeData object.

The following lists the differences, compared to the standard ThemeData.from factory, as well as the rationale behind the made design choices and changes to the defaults.

  • scaffoldBackgroundColor has its own color property in FlexColorScheme and can if so desired differ from the ColorScheme.background color. When using primary color blended surfaces and backgrounds, it is important to be able to vary the very prominent ScaffoldBackgroundColor separately from other surfaces and backgrounds.

  • The dialogBackgroundColor uses the ColorScheme.surface color instead of the default ColorScheme.background. In order to preserve the elevationOverlayColor in dark mode when ColorScheme.surface and ColorScheme.background differs due to different surface blends, the ColorScheme.surface was used to ensure dialogs that are always elevated gets the overlay color applied in dark theme mode. For more info, see issue #90353.

  • The indicatorColor is same as effectiveTabColor. It uses a function with logic to determine its color based on if a TabBarTheme was selected that should work on current AppBar background color, or on surface/background colors.

  • For toggleableActiveColor the ColorScheme.secondary color is used. The Flutter default just uses the default ThemeData colors and not the actual colors you define in the ColorScheme you create your theme from. Perhaps an oversight in Flutter? See issue #65782. See also practical examples in Roads to ThemeData. This color property will be deprecated in Flutter, see issue 91772.

  • Flutter themes created with ThemeData.from do not define any color scheme related color for the primaryColorDark color, FlexColorScheme does. See issue #65782. The ThemeData.from leaves this color at ThemeData factory default, this may not match your scheme. Flutter SDK Widgets seldom use this color, so the issue is rarely seen. This color property will be deprecated in Flutter, see issue 91772.

  • Flutter themes created with ThemeData.from do not define any color scheme based color for the primaryColorLight color, FlexColorScheme does. See issue #65782. The ThemeData.from leaves this color at ThemeData factory default this may not match your scheme. Flutter SDK Widgets seldom use this color, so the issue is rarely seen. This color property will be deprecated in Flutter, see issue 91772.

  • Flutter themes created with ThemeData.from do not define any color scheme based color for the secondaryHeaderColor color, FlexColorScheme does. See issue #65782. ThemeData.from leaves this color at ThemeData factory default this may not match your scheme. Flutter SDK Widgets seldom use this color, so the issue is rarely seen. This color property will be deprecated in Flutter, see issue 91772.

  • Background color for AppBarTheme can use a custom theme color in both light and dark themes, that is not dependent on the theme's primary or surface color. In the versions prior to Flutter 2.0.0 doing this was very difficult to do, as presented in #50606. A new feature in Flutter 2.0.0 implemented via #71184 makes this easy and better. FlexColorScheme's implementation has been changed to use this new AppBarTheme feature starting from version 2.0.0-nullsafety.2.

  • The AppBarTheme elevation defaults to 0, an iOs style influenced opinionated choice. It can easily be adjusted directly in the FlexColorScheme definition with property value appBarElevation without creating a sub theme or using copyWith.

  • For the BottomAppBarTheme when not using subThemes, we in M2 mode always get a BottomAppBarTheme with at least background color defined to be ColorScheme.surface, even if bottomAppBarElevation is null. This is done to avoid issues with deprecation of ThemeData.bottomAppBarColor that is still used in M2 mode defaults. When using M3 mode and if bottomAppBarElevation is null, we actually get a default BottomAppBarTheme() all null theme made by FlexSubThemes.bottomAppBarTheme.

  • In TextSelectionThemeData, the Flutter default for selectionColor is colorScheme.primary with opacity value 0.4 for dark-mode and 0.12 for light mode. Here, primary with 0.5 opacity for dark-mode, and 0.3 for light mode is used. The default for selectionHandleColor is colorScheme.primary, here we use the slightly darker shade primaryColorDark instead, which does not have a proper color scheme color value in Flutter standard ColorScheme based themes.

  • A predefined slightly opinionated InputDecorationTheme is used. It sets filled to true and fill color to the color scheme's primary color with opacity 0.035 in light mode and with opacity 0.06 in dark-mode. Since the used theme, does not define a border property of TextField, an app can easily use both the default underline style, or the outline style by just specifying OutlineInputBorder(), when an outlined TextField is desired. If you don't want the filled style, or the primary-colored borders in dark-mode, you can override them back with copyWith.

  • The property fixTextFieldOutlineLabel is set to true by default, it looks better. The only reason why it is not the default in Flutter is for default backwards legacy design compatibility.

  • For ThemeData.buttonTheme the entire color scheme is passed to its colorScheme property and it uses textTheme set to ButtonTextTheme.primary, plus minor changes to padding and tap target size. These modifications make the old buttons almost match the default design and look of their corresponding newer buttons. It makes the RaisedButton looks very similar to ElevatedButton, OutlineButton to OutlinedButton and FlatButton to TextButton. There are some differences in margins and looks, especially in dark-mode, but they are very similar. These legacy buttons are deprecated in Flutter and some no longer exist. The buttonTheme is also on a deprecation path and will be removed when it is.

    NOTE:
    Since the old buttons have been deprecated in Flutter 2.0.0 they are no longer presented or used in code in FlexColorScheme and its examples. However, FlexColorScheme still defines the above theme for them. Defining the theme does not yet cause any deprecation warnings or errors, as long as that is the case, this theming will be kept available to support out of the box nice themes for the old buttons as before. It is however stated and noted in the master channel that the next release (after 2.10) of Flutter will completely remove the old buttons and the old buttonTheme may then be deprecated and later removed as well. FlexColorScheme will then need to deprecate and remove the old button theme.

  • The ChipThemeData contained a design bug in older versions of Flutter that made the selected ChoiceChip widget look disabled in dark-mode, regardless of if it was created with ThemeData or ThemeData.from factory. See issue: https:///github.com/flutter/flutter/issues/65663 The ChipThemeData] modification originally used in core FlexColorScheme fixed the issue. The issue has been resolved but the same ChipThemeData is still in use in core style for backward style compatibility.

  • For TabBarTheme, the Flutter standard selected tab and indicator color is, onSurface in dark-mode and onPrimary in light mode, which is designed to fit an AppBar colored TabBar. This is kept, and the default via FlexTabBarStyle.forAppBar style, with a minor modification. If AppBar is "light", then black87 is used, not black. This is the same as the textTheme for AppBar in light AppBar brightness. If the FlexTabBarStyle.forBackground style was used, the selected color is always color scheme primary color, which works well on surface, background and scaffold background colors.

    The unselected TabBar color when FlexTabBarStyle.forBackground style is used, is always the onSurface color with 60% opacity. This is also the used color if the AppBar background color brightness is light AND its color is white, surface or background colored. When the style FlexTabBarStyle.forAppBar is used, the unselected tab bar color is the selected tab color with 70% opacity. This opacity value is the same as Flutter default for the default theme that is also designed for AppBar usage.

  • The BottomNavigationBarThemeData uses color scheme primary color for the selected item in both light and dark theme mode. Flutter default uses primary in light mode but defaults to secondary color in dark mode. Using primary color is a design used on iOS by default for the bottom navigation bar in both theme modes. We agree and think it looks better as the default choice for apps in both theme modes.

  • FlexColorScheme tooltips also include a boolean property tooltipsMatchBackground, that can be toggled to not use Flutter's Material default design that has a theme mode inverted background. Tooltips using light background color, in light theme and dark one in dark theme, are commonly used on the Windows desktop platform. You can easily tie this extra property to the used platform to make an automatic platform adaptation of the tooltip style if you like. You can also use it to give users a preference toggle where they change the tooltip style to their liking.

  • The FlexColorScheme property transparentStatusBar is set to true by default. It is used to make the AppBar one-toned on Android devices, like on iOS devices. Set it to false if you want to restore the default Android two toned design.

Component Themes

FlexColorScheme also offers opinionated component themes that enable you to get more heavily styled and themed widgets automatically. You can customize these styles further via FlexSubThemesData.

These component themes are as stated opinionated design choices. You may or may not like them. They can be modified and tuned, some of them only a bit, while others offer quite extensive quick configuration options. The intent is to keep the component themes visual results consistent from version to version. However, changes in the SDK and supporting new features may require minor style breaking changes to them from time to time.

In Material-2 mode, the defaults for these component themes, draw inspiration from Material-3. They are inspired by the Material-3 Design Guide, within reasonable limits of Flutter's Material-2 based theming capabilities. When you enable opinionated component themes and keep using Material-2, you get a design that is quite similar to Material-3, without actually committing to using Material-3.

The component themes are modified and extended as Material-3 features reaches the Flutter stable channel, to use actual Material-3 implementations in Flutter when opting in on using Material-3, and enabling the FlexColorScheme component themes. Material-3 will eventually become the default and only Material theming avilable in Flutter. FlexColorScheme component themes do make some opinionated design choices concerning them as well, but they are very minor.

To enable the optional component theming feature in FlexColorScheme, pass in a default FlexSubThemesData() to its subThemesData property. This gives you the FlexColorScheme default opinionated component theme setup. Naturally FlexColorScheme would not be "flex" if the FlexSubThemesData data class did not also contain many optional quick configuration parameters for the opinionated component themes.

The list of properties in the configuration class has grown very large. While it can be a bit tricky to maintain it, using it is easy and quite a convenient way to adjust commonly used properties on UI component widget themes using simple "flat" property values. No need for deep ShapeBorder definitions on every component theme for a simple border radius change, nor for the complex MaterialState properties. At least not as long as choices and offered flat config options cover what you need.

A common use case for FlexSubThemes is easy to use customization of default border radius on all Flutter UI components and elements that supports border radius either via ShapeBorder or BorderRadiusGeometry. This can be done with a single property, defaultRadius.

When you opt in on using the component themes, the FlexColorScheme.toTheme method uses the passed in FlexSubThemesData configuration data object, passed in via FlexColorScheme.subThemesData, to create the component themes.

In some cases, typically for older core related "legacy" component theme cases, the themes are created directly in the toTheme method. However, in most cases separate static sub-theme helper functions from the FlexSubThemes class are used. The component themes that are defined directly in the toTheme method, will be moved into the FlexSubThemes class as well in future updates.

You can also use these static component theme helpers without using FlexColorScheme to define custom components themes, or even without using FlexColorScheme at all.

The FlexSubThemesData configuration has no direct impact on these static helpers. It is FlexColorScheme that uses the FlexSubThemesData class to configure the opt-in sub-themes based on the setup information provided via FlexColorScheme.subThemesData.

These are the component static theme helpers available in FlexSubThemes:

  • AppBarTheme for AppBar via appBarTheme.
  • BottomAppBarTheme for BottomAppBar via bottomAppBarTheme.
  • BottomNavigationBarThemeData for BottomNavigationBar via bottomNavigationBar.
  • BottomSheetThemeData for BottomSheet via bottomSheetTheme.
  • ButtonThemeData for old deprecated buttons, via buttonTheme.
  • CardTheme for Card via cardTheme.
  • CheckboxThemeData for Checkbox via checkboxTheme.
  • ChipThemeData for Chip via chipTheme.
  • DatePickerThemeData for DatePicker via datePickerTheme.
  • DialogTheme for Dialog via dialogTheme.
  • DrawerThemeData for Drawer via drawerTheme.
  • DropdownMenuThemeData for DropDownMenu via dropdownMenuTheme.
  • ElevatedButtonThemeData for ElevatedButton via elevatedButtonTheme.
  • FilledButtonThemeData for FilledButton via FlexSubThemes.filledButtonTheme.
  • FloatingActionButtonThemeData for FloatingActionButton via floatingActionButtonTheme.
  • IconButtonThemeData for IconButton via iconButtonTheme.
  • InputDecorationTheme for InputDecoration via inputDecorationTheme.
  • MenuBarThemeData for MenuBar via menuBarTheme.
  • MenuButtonThemeData for MenuButton via menuButtonTheme.
  • MenuThemeData for MenuBar, MenuAnchor and DropDownMenu via menuTheme.
  • NavigationBarThemeData for NavigationBar via navigationBarTheme.
  • NavigationDrawerThemeData for NavigationDrawer via navigationDrawerTheme.
  • NavigationRailThemeData for NavigationRail via navigationRailTheme.
  • OutlinedButtonThemeData for OutlinedButton via outlinedButtonTheme.
  • PopupMenuThemeData for PopupMenuButton via popupMenuTheme.
  • RadioThemeData for Radio via radioTheme.
  • SegmentedButtonThemeData for SegmentedButton via segmentedButtonTheme.
  • SliderThemeData for Slider via sliderTheme.
  • SnackBarThemeData for SnackBar via snackBarTheme.
  • SwitchThemeData for Switch via switchTheme.
  • TabBarTheme for TabBar via tabBarTheme.
  • TextButtonThemeData for TextButton via textButtonTheme.
  • TextSelectionThemeData for TextField via textSelectionTheme.
  • TimePickerThemeData for TimePickerDialog via timePickerTheme.
  • ToggleButtonsThemeData for ToggleButtons via toggleButtonsTheme.
  • TooltipThemeData for Tooltip via tooltipTheme.

In ToggleButtons hover, press, selected and focus states are not an exact match for the main buttons. It does not have as flexible styling as the main buttons. The theme mimics the style of the OutlinedButton for not selected buttons, and the style of ElevatedButton for selected button. It does not support MaterialStateProperty and has only one state for different parts of the button. The selected and not selected, states would need different property values to be able to match the general buttons. It can therefore not fully match the same theme style, as the Material states used on two different ButtonStyleButton buttons that it should match, but it is quite close. The ToggleButtons default styling in FlexColorScheme might well get some design changes for its own opinionated defaults in future release. If it does, it will still support its current default via configuration options.

The theme ButtonThemeData (deprecated in version 5.1.0) is still included to provide a very similar theme style on the deprecated and partially SDK removed legacy buttons RaisedButton, OutlineButton and FlatButton as on the current main buttons. It is not an exact match, since the legacy buttons do not offer as flexible styling as the newer buttons. The legacy button theme follows and match the styling on ToggleButtons when it comes to hover, press, selected and focus. Please consider phasing out the legacy buttons, as they are deprecated and will be removed from the Flutter SDK in the next stable release. Their theme, the ButtonThemeData will also soon be deprecated and later removed in Flutter.

The following widgets have rounded corners, but are excluded from the component border radius theming for now:

  • Tooltip, generally so small that larger prominent rounding the opinionated sub-theming is designed for, is not a good fit. FlexColorScheme does include out of the box theming options for tooltips, that also adapts to color branding when opting in on sub themes, it also gets a bit more rounded when opting in.
  • Scrollbar, rounding on edges of scrollbars are left to platform default.
  • The AppBar and BottomAppBar shape properties are left to their defaults.
  • SnackBar the floating SnackBar should be themed to also include border radius, but the none floating one should remain straight. This cannot be done with current Flutter SDK theming features. See known issues for more info
  • Drawer should have rounded corners on shown side edge. It is possible to assign a Shape in the drawer theme. But Drawer uses the same theme, when used as Drawer and EndDrawer, and the rounding should be on end edge on Drawer and start edge in EndDrawer. It seems we cannot do this without having two Shapes in its theme or other usage behavior modifying it. A default behavior in SDK can implement it by looking up if Drawer is being used in Scaffold as Drawer or EndDrawer, but support via theme is needed too.

You can find more information about available component theme helpers in the API docs. You can as mentioned in the API guide also use these static sub-theme helpers to manually define widget sub-theme, and even further modify them using their copyWith methods.

Edit this page on GitHub
Deep dives
Flutter Theming