# API Guide The [API reference documentation](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/flex_color_scheme-library.html) for FlexColorScheme generated from code document comments is very thorough. It should cover most questions you might have. An overview of key APIs is presented below. It may be extended with more information and examples in future updates. These updates will be influenced by what questions users raise about the API. You can create FlexColorScheme based `ThemeData` objects using two different APIs: 1. **FlexThemeData** static extension on `ThemeData`. 2. **FlexColorScheme.toTheme** class and method. ## FlexThemeData API reference: [**FlexThemeData**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexThemeData.html) There are separate APIs for creating the light theme mode, and dark theme mode `ThemeData`: * [**FlexThemeData.light()**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexThemeData/light.html) * [**FlexThemeData.dark()**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexThemeData/dark.html) **Example: FlexThemeData** Using this API is very familiar, it looks a lot like `ThemeData.light` and `dark`, but with Flex prepended. They, of course, have a lot of additional properties, but the basic usage is simple. ```dart class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( title: 'API Guide', theme: FlexThemeData.light(scheme: FlexScheme.mandyRed), darkTheme: FlexThemeData.dark(scheme: FlexScheme.mandyRed), themeMode: ThemeMode.system, home: MyHomePage(title: 'Flutter Demo Home Page'), ); ``` The `FlexThemeData` is a static extension on `ThemeData` to define a `FlexColorScheme` object and return the `ThemeData` object defined by its instance, using its `FlexColorScheme.toTheme` method, all done in one step with a more compact API. Using e.g. `FlexThemeData.light()` is a bit shorter than `FlexColorScheme.light().toTheme`, and it may also feel more familiar since you get a `ThemeData` object directly, that you can use just like any other `ThemeData` object produced by Flutter's different built-in `ThemeData` factory constructors. ## FlexColorScheme API reference: [**FlexColorScheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme-class.html) The original way to create FlexColorScheme based `ThemeData` objects is to use the package namesake [`FlexColorScheme`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme-class.html) class and then use its [`toTheme`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme/toTheme.html) method to make and return the `ThemeData` object specified by your immutable `FlexColorScheme` configuration. Usually you should **not** use the raw default [`FlexColorScheme()`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme/FlexColorScheme.html) constructor to create your `FlexColorScheme` object, you should prefer using its two factories: * [**FlexColorScheme.light()**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme/FlexColorScheme.light.html) * [**FlexColorScheme.dark()**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme/FlexColorScheme.dark.html) These factories are used to make `FlexColorScheme` based `ThemeData` definitions for light and dark theme mode respectively. They offer many additional parameters over the raw default constructor, that are used to create more nuanced and computed `ColorScheme` definitions, that are then used by the created `ThemeData`. Here is how you would use them to define identical themes as the above ones, where we used `FlexThemeData.light` and `.dark`: **Example: FlexColorScheme** Making `ThemeData` with FlexColorScheme's namesake class, is a bit more verbose, but it does the same thing. Strictly speaking it is `FlexThemeData` that does the same thing, since it uses `FlexColorScheme.toTheme` under the hood. ```dart class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( title: 'API Guide', theme: FlexColorScheme.light(scheme: FlexScheme.mandyRed).toTheme, darkTheme: FlexColorScheme.dark(scheme: FlexScheme.mandyRed).toTheme, themeMode: ThemeMode.system, home: MyHomePage(title: 'Flutter Demo Home Page'), ); ``` The `FlexColorScheme.light().toTheme` and `FlexThemeData.light()`, and its dark counterparts, all have the same properties and are interchangeable. The `light` and `dark` parameters differ slightly, due to a few different features for light and dark themes. ## Common Properties Important properties for `FlexColorScheme.light()` and `FlexThemeData.light()`, as well as for `FlexColorScheme.dark()` and `FlexThemeData.dark()`, are presented below. The examples use `FlexThemeData`, but they are identical when using `FlexColorScheme`. The two most commonly used properties to define used colors in the produced `ThemeData` are: * **scheme** a [`FlexScheme`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexScheme.html) enum value used to select which predefined color scheme to use for the theme. * **colors** a [`FlexSchemeColor`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSchemeColor-class.html) object used to define custom colors to be used when creating the theme. If you specify both `scheme` and `colors`, the custom colors in `colors`, have higher precedence and are used, and the `scheme` property is ignored. If you specify neither, then `scheme` defaults to `FlexScheme.material`. You can also create a custom `FlexColorScheme` based theme, from a Flutter standard `ColorScheme` object, by providing it a `colorScheme`. * **colorScheme** a [`ColorScheme`](https://api.flutter.dev/flutter/material/ColorScheme-class.html) object used to create a custom `FlexColorScheme` based theme, from color definitions you already have in a standard `ColorScheme`. This property also exists in the default constructor. If you use `colorScheme` the colors in the provided `colorScheme` will override any values you have given in the `scheme` or `colors` properties. * The direct color properties available in the constructors, e.g. `primary`, `primaryContainer`, etc., that are all named like the same color properties in `ColorScheme` or e.g. `scaffoldBackground` in `ThemeData`, will override any corresponding color values that would be set via any other color affecting properties provided via `scheme`, `colors` and also the ones in a `colorScheme`. The direct color properties provide an alternative way to override individual colors values in built-in `scheme`, `colors` or provided `colorScheme`. Not all color properties in a `ColorScheme` are available as direct color property values, but commonly used ones are. FlexColorScheme has shortcut enum properties that you can use to quickly adjust the theme design for your **AppBar** and **TabBar**. * **appBarStyle** a [`FlexAppBarStyle`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexAppBarStyle.html) enum value used to define the themed color of the **AppBar** background color. * [**tabBarStyle**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme/tabBarStyle.html) a [`FlexTabBarStyle`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexTabBarStyle.html) enum value used to select preferred style for used **TabBarTheme** theme. * **appBarOpacity** a double value, can also be used to define the opacity of the AppBar background. An interesting and unique feature of FlexColorScheme is its capability to automatically create color schemes and resulting themes that blend in the primary color into different surfaces. You can vary this blending depending on the surface type and use different blend strengths. This feature is only available via the factory constructors and their `ThemeData` extensions, not via the default raw `FlexColorscheme()` constructor. To use the surface blending features use the properties **surfaceMode** and **blendLevel**. * **surfaceMode** a [`FlexSurfaceMode`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSurfaceMode.html) enum value used to select the mode for blending in primary color into surface, background, scaffoldBackground and dialogBackground colors. * **blendLevel**, integer value, sets the blend level strength used by the used `surfaceMode`. The blend level is the integer decimal value of the alpha value used in the alpha blend function. It mixes one color with another, by using alpha opacity value in the color of a surface put on top of another surface with opaque color, and returns the result as one opaque color. You can also use properties like **inputColors**, **swapColors** and e.g. **useMaterial3ErrorColors** to modify the main input colors, before they are used to create the effective `ColorScheme` used in produced `ThemeData`. * **inputColors** integer value that defines the number of the six main scheme colors to be used when creating the effective `ColorScheme`. A convenience property that allows you to vary which colors to use of input primary, secondary and tertiary colors and their container colors, when FlexSchemeColor creates its effective `ColorScheme` from the input colors. The integer number corresponds to using: 1. Only the primary color 2. Primary & Secondary colors 3. Primary + container & Secondary colors 4. Primary + container & Secondary + container 5. Primary + container & Secondary + container & tertiary colors 6. Primary + container & Secondary + container & tertiary + container 7. Primary + Secondary + Tertiary Computed color values are used by the ones being left out, the computed colors are derived from included ones. You can create a theme that uses only different shades and tones derived from the input `primary` color, by setting `inputColors` to 1. **Defaults to 6**, always using all 6 main input colors if they are defined. * **swapColors** boolean value. When true, the primary and primaryContainer colors will be swapped with their secondary counterparts. Set this flag to true, if you want to make a theme where your primary and secondary colors are swapped, compared to how they are defined in the given input color properties or selected pre-defined color scheme. This is useful if you want to do this with the pre-defined schemes for more theme options. If you are explicitly defining all your theme colors, you can define them in any desired order. Even if you do that, this feature, if used, will still swap whatever colors you defined for primary and secondary. You can also offer this feature as an easy end user modifiable theme option. Another usage possibility is to set `swapColors` to true only for the dark mode and use your color scheme primary and secondary the other way around in dark mode. * **useMaterial3** boolean value. Defaults to false. A flag used to opt in to new SDK Material-3 features. Same property as in `ThemeData`, see [API doc](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexColorScheme/useMaterial3.html) or [Flutter API docs](https://api.flutter.dev/flutter/material/ThemeData/useMaterial3.html) for more information. * **useMaterial3ErrorColors** boolean value. Set it to true to use the new Material-3 error colors. If `useMaterial3ErrorColors` is false, the resulting `ColorScheme` and `ThemeData` will use Material-2 default error colors or error colors as defined by the built-in color schemes. Thus, using the same error colors as in FlexColorScheme versions before version 5. If `useMaterial3ErrorColors` is true, the resulting `ColorScheme` and `ThemeData` will use the Material-3 design guide error colors. Key color seed generated ColorSchemes always uses the Material-3 design guide error colors, or error colors from its customized `TonalPalette` generation setup. **Defaults to false**. The new M3 error colors are generally nicer looking. If your theme is using red color shades, you can try both options to see which option works better with your theme's red colors. That would be the red error color option that is more distinguishable from your main red theme colors. * **swapLegacyOnMaterial3** boolean value. Set it to true, to automatically swap secondary and tertiary colors on built-in color schemes, when `useMaterial3` is true, if the scheme benefits from it to better match the Material-3 color system design intent. Starting with FlexColorScheme version 6.1.0, built-in color schemes, defined via `FlexSchemeColor`, have a flag `swapOnMaterial3`. When defined to be true, the scheme will benefit if the `secondary` and `tertiary` colors, including their containers, are swapped when using Material-3. Most FlexColorScheme color schemes were designed with M2 usage in mind, before M3 existed. They may often have their `swapOnMaterial3` set to true. If this flag is false, it may mean that its `FlexSchemeColor` was designed for M3 or that it won't benefit from swapping its secondary and tertiary colors. In the [Scheme Reference](/scheme_reference), you can see which schemes have the flag defined to true. Using a seed-generated color scheme based on built-in FlexSchemeColor colors is another way to make them suitable for the M3 Color system. However, in some cases, the secondary color in their design may not be in-line with the M3 color system design intent, especially if you use the config that also uses the hue from the secondary color to make tonal palettes for it. In some legacy FlexSchemeColor color designs, this can be fixed if we swap the secondary and tertiary colors. To make FlexSchemeColor designs color designs that benefit from it automatically swap secondary and tertiary colors when `useMaterial3` is set to true, set `swapLegacyOnMaterial3` to true. It defaults to false, for backward compatibility, but it is recommended to turn it on when using Material-3 and its color system. If you use seeded color schemes with Material-2, `useMaterial3` flag is false, then it may be preferable to keep `swapOnMaterial3` false for more prominent colors on secondaries. This color swap has higher priority than `swapColor`, using it will always happen on the effective result of `swapLegacyOnMaterial3` and `useMaterial3`, and value of `swapOnMaterial3` in currently used built-in scheme `FlexSchemeColor`. If a custom `colorScheme` is passed in, or any of the direct color properties `secondary`, `secondaryContainer`, `tertiary` or `tertiaryContainer`, then it is assumed a custom scheme or overrides, are being used and the `swapLegacyOnMaterial3` setting does nothing. The Themes Playground app defaults to setting `swapLegacyOnMaterial3` to ON (true), but allows you to turn it OFF. Defaults to false, for backwards compatibility, but prefer setting it to true if you also set `useMaterial3` to true. **Example: Demo of Common Properties** In this example, we use many of the above-discussed properties: ```dart theme: FlexThemeData.light( scheme: FlexScheme.flutterDash, usedColors: 4, surfaceMode: FlexSurfaceMode.highScaffoldLowSurface, blendLevel: 20, appBarStyle: FlexAppBarStyle.background, appBarOpacity: 0.95, tabBarStyle: FlexTabBarStyle.forBackground, swapColors: true, useMaterial3ErrorColors: true, ), darkTheme: FlexThemeData.dark( scheme: FlexScheme.flutterDash, usedColors: 4, surfaceMode: FlexSurfaceMode.highScaffoldLowSurface, blendLevel: 15, appBarStyle: FlexAppBarStyle.background, appBarOpacity: 0.90, tabBarStyle: FlexTabBarStyle.forBackground, useMaterial3ErrorColors: true, ), ``` This produces an app with a theme looking like this, when we try it in the [**Copy Playground**](/copy_playground) app:
[API basic 1](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-01-basics.png)   [API basic 2](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-02-basics.png)   [API basic 3](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-03-basics.png)   [API basic 4](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-04-basics.png)
_The **Copy Playground** theme presentation app, with above FlexThemeData setup._
## Use FlexColorScheme or FlexThemeData? When should you use `FlexColorScheme.light().toTheme` instead of `FlexThemeData.light()`? If all you need is the `ThemeData` object, then you may prefer using `FlexThemeData.light()` due to its shorter and more familiar syntax. However, if you need access to the `ColorScheme` that will be made by `toTheme` when it creates `ThemeData`, you may prefer first defining a `FlexColorScheme` object. You can then use the `FlexColorScheme.toScheme` method to get the `ColorScheme` it will use in its created `ThemeData`. You can use this `ColorScheme` the get access to the identical `ColorScheme`, regardless of what properties you used to define and generate it with in your `FlexColorScheme` configuration. **Example: Using ColorScheme from FlexColorScheme.toScheme** You often need access to FlexColorScheme's `ColorScheme` if you make custom component themes in order to use theme matching colors in them. ```dart // A function to make custom ThemeData using FlexColorScheme // and a custom ToggleButtonsThemeData component theme. ThemeData myLightTheme({ }) { // We need to use the ColorScheme defined by the ThemeData that // FlexColorScheme will create based on our configuration in our // custom component theme. We first create the `FlexColorScheme` object: final FlexColorScheme flexScheme = FlexColorScheme.light( scheme: FlexScheme.flutterDash, surfaceMode: FlexSurfaceMode.highScaffoldLowSurface, blendLevel: 10, appBarStyle: FlexAppBarStyle.background, appBarOpacity: 0.95, tabBarStyle: FlexTabBarStyle.forBackground, ); // Then get the `ColorScheme` defined by our FlexColorScheme configuration, // using its `toScheme` method. final ColorScheme colorScheme = flexScheme.toScheme; // We can the return the `ThemeData` from our `FlexColorScheme`, with // our custom component theme added to it, where its customizations uses // color that the `ColorScheme` in the return `ThemeData` also gets. return flexScheme.toTheme.copyWith( // Add our custom toggle buttons component theme. toggleButtonsTheme: toggleButtonsTheme(colorScheme), ); } // ToggleButtons theme. ToggleButtonsThemeData toggleButtonsTheme(ColorScheme colorScheme) => ToggleButtonsThemeData( selectedColor: colorScheme.onPrimary, color: colorScheme.primary.withOpacity(0.85), fillColor: colorScheme.primary.withOpacity(0.85), hoverColor: colorScheme.primary.withOpacity(0.2), focusColor: colorScheme.primary.withOpacity(0.3), borderWidth: 1.5, borderColor: colorScheme.primary, selectedBorderColor: colorScheme.primary, borderRadius: BorderRadius.circular(20), ); ``` Above you could also create the entire `ThemeData` from the `FlexColorScheme` instance `flexScheme` above. Extract its `ColorScheme` and use it to make the component theme `toggleButtonsTheme`, and then use `copyWith` on the already created `ThemeData` that you return as `ThemeData`. Both work, the above should, in theory, be marginally more resource efficient, but it probably does not matter in practice. ## Generated ColorScheme Flutter has `ColorScheme.fromSeed` to make delightful Material-3 specification based **computational** ColorSchemes. With **FlexColorScheme** you can use the identical algorithm that is used by `ColorScheme.fromSeed`. You can also completely customize it, while still be producing a `ColorScheme` that adheres to the Material-3 color system, but primes the color generation engine a bit differently. Since `ColorScheme.fromSeed` only uses one single color as seed color, and always the same `ColorScheme` generation parameters, the amount of variation it provides is a bit limited, and the results also tend to be soft pastel color oriented. As we get used to them, they will all start looking quite similar. By priming the `FlexColorScheme` customizable `ColorScheme` generation differently, you can create more varied results that are not so repetitive of what has already been seen before, even if it still uses the same M3 color system design principle, based on tonal palettes. You can read and see a brief explanation in the Themes Playground guide about what the [**tonal palettes**](/playground#tonal-palettes) are. To make a key color seed generated `ColorScheme` with FlexColorscheme, using its effective input `primary` color as the seed key, pass in a default `FlexKeyColors()` to the `keyColors` property. With this default you get a computed `ColorScheme` that is identical to the one you would have gotten if you used `ColorScheme.fromSeed` with the effective input `primary` color from your `FlexColorScheme`. With `FlexKeyColors` you can also use the `secondary` and `tertiary` colors in your `FlexColorScheme` as input color keys, that are then used when generating the secondary and tertiary tonal palettes respectively. Please see the API documentation for more information about additional parameters in `FlexKeyColors`. Starting from version 6.0.0, FlexColorScheme no longer directly depends on package [Material Color Utilities package](https://pub.dev/packages/material_color_utilities), which is also used by Flutter SDK. Instead, it uses package [FlexSeedScheme](https://pub.dev/packages/flex_seed_scheme) that depends on it. As a part of this change classes `FlexTones`, `FlexTonalPalette` and `FlexCorePalette` where moved into the package **FlexSeedScheme**. FlexColorScheme still exports these classes. If you were using them directly before, you can still do so without adding the FlexSeedScheme package. API reference: [**FlexKeyColors**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexKeyColors-class.html) By specifying a `FlexTones()` configuration for `tones` in `FlexColorScheme` you can further adjust how the `ColorScheme` generation algorithm computes the primary, secondary and tertiary tonal palettes. The properties `Chroma` and `MinChroma`, prepended with `primary`, `secondary` and `tertiary` for each tonal palette from corresponding key color, adjust how the algorithm uses the input colors when it generates the tonal palettes from the key colors. See API reference for details: * [**primaryChroma**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/primaryChroma.html) * [**primaryMinChroma**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/primaryMinChroma.html) * [**secondaryChroma**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/secondaryChroma.html) * [**secondaryMinChroma**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/secondaryMinChroma.html) * [**tertiaryChroma**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/tertiaryChroma.html) * [**tertiaryMinChroma**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/tertiaryMinChroma.html) You can also modify which tone in the generated tonal palettes is mapped to what `ColorScheme` color, within the limits that it only allows mapping tones from each tonal palette to the colors in the ColorScheme that in Material-3 color system design use the tonal palette in question, but you can change used tone to be different from the Material-3 guide specification and values used in Flutter SDK. To make custom `FlexTones()`, prefer using the theme mode appropriate constructor `FlexTones.light()` or `FlexTones.dark()` that have defaults that create the setup for the Material-3 spec used in Flutter `ColorScheme.fromSeed`, but where each property can be changed from the default as preferred. There are other predefined `FlexTones` configurations in addition to the default Material-3 guide spec matching one. You can use them as they are, or as examples of how to create your own custom `tones` configurations. Made a great one? Please share it in the FlexColorScheme GitHub repository's show and tell [discussions](https://github.com/rydmike/flex_color_scheme/discussions/categories/show-and-tell) forum. Maybe we can add it as another predefined option. See API reference for more details on **FlexTones**: * Class [**FlexTones**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones-class.html) * Light mode default value factory [**FlexTones.light**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.light.html), default and the same as Flutter SDK M3 setup for a light ColorScheme. * Dark mode default value factory [**FlexTones.dark**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.dark.html), default and same as Flutter SDK M3 setup for a dark ColorScheme. * Material-3 spec tones constructor [**FlexTones.material**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.material.html), default and same as Flutter SDK M3 setup. * Vivid color tones constructor [**FlexTones.vivid**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.vivid.html), more vivid colors, or at least closer in chroma to the used seed key color, as it uses chroma from all key colors as given. * Vivid surfaces tones constructor [**FlexTones.vividSurfaces**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.vividSurfaces.html), like vivid, but with double the chroma in each surface tonal palette. * Vivid background tones constructor [**FlexTones.vividBackground**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.vividBackground.html), like vividSurfaces, but with tone mapping for surface and background color swapped. * Soft tones constructor [**FlexTones.soft**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.soft.html), softer and earthier tones than M3 FlexTones.material. * High contrast tones constructor [**FlexTones.highContrast**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.highContrast.html), can be used for more color-accessible themes. It offers more contrast between colors. * Ultra contrast tones constructor [**FlexTones.ultraContrast**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.ultraContrast.html), a tonal palette extraction setup that results in a very high contrast version of produced ColorsSchemes, it is less colorful and more focused a pure white or pure dark backgrounds and foreground colors. * Jolly tones constructor [**FlexTones.jolly**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.jolly.html), creates a tonal palette extraction setup that results in a more jolly and colorful ColorsSchemes. * One hue tones constructor [**FlexTones.oneHue**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.oneHue.html), Create a M3 tonal palette tones extraction, but with no hue rotation from primary if no ARGB key color is provided for tertiary palette. This setup will if only one seed color is used, produce a more chromatic color set than `FlexTones.material`. Since it does not rotate hue from primary to get hue for tertiary, it will also create a color scheme using tonal palettes that are based on the same hue, but with different chroma. In simple terms, all colors are shades of the provided key color to seed the tonal palettes. We can get a nice one hue toned theme with this configuration. * [**FlexTones.candyPop**](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexTones/FlexTones.candyPop.html) for a high contrast, candy popping theme. It has tone 100, which is white surface and background in light mode and very dark tone 6, dark mode. This FlexTones uses the paletteType extended via [FlexPaletteType.extended](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexPaletteType.html), for additional tone fidelity. * [**FlexTones.chroma**]() for a theme where the chroma in each seed color is used as is with any min limitation. Chroma in passed in color can even be zero, producing a greyscale tonal palette as the palette. It has tone 100, which is white surface and background in light mode and very dark tone 6, dark mode. This FlexTones also uses the paletteType extended via [FlexPaletteType.extended](https://pub.dev/documentation/flex_seed_scheme/latest/flex_seed_scheme/FlexPaletteType.html), for additional tone fidelity. **Example: FlexColorScheme with keyColors and Tones** Here we use a key color generated ColorScheme, while using otherwise same property values as in the previous example. ```dart theme: FlexThemeData.light( scheme: FlexScheme.flutterDash, usedColors: 4, surfaceMode: FlexSurfaceMode.highScaffoldLowSurface, blendLevel: 20, appBarStyle: FlexAppBarStyle.background, appBarOpacity: 0.95, tabBarStyle: FlexTabBarStyle.forBackground, swapColors: true, keyColors: const FlexKeyColors( useSecondary: true, useTertiary: true, ), tones: FlexTones.vivid(Brightness.light), ), darkTheme: FlexThemeData.dark( scheme: FlexScheme.flutterDash, usedColors: 4, surfaceMode: FlexSurfaceMode.highScaffoldLowSurface, blendLevel: 15, appBarStyle: FlexAppBarStyle.background, appBarOpacity: 0.90, tabBarStyle: FlexTabBarStyle.forBackground, keyColors: const FlexKeyColors( useSecondary: true, useTertiary: true, ), tones: FlexTones.vivid(Brightness.dark), ), ``` Above we used one of the predefined custom tone setups called `FlexTones.vivid`. Making custom tones is simple, the code for this predefined example is: ```dart static FlexTones vivid(Brightness brightness) => brightness == Brightness.light ? const FlexTones.light( primaryTone: 30, primaryChroma: null, secondaryChroma: null, tertiaryChroma: null, primaryMinChroma: 50, ) : const FlexTones.dark( onPrimaryTone: 10, primaryContainerTone: 20, onErrorContainerTone: 90, primaryChroma: null, secondaryChroma: null, tertiaryChroma: null, primaryMinChroma: 50, ); ``` When we try the above `FlexThemeData` config, again in the [**Copy Playground**](/copy_playground) app, we get an application with this theme:
[API keyColor 5](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-05-key.png)   [API keyColor 6](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-06-key.png)   [API keyColor 7](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-07-key.png)   [API keyColor 8](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-08-key.png)
_The **Copy Playground** theme presentation app, with the above FlexThemeData setup, using **keyColors** generated ColorScheme with custom **tones**._
## Component Themes A more opinionated theme and style can be created by passing in a default `FlexSubThemesData()` constructor to the `FlexColorScheme` or `FlexThemeData`, property `subThemesData`. By default, the component themes take inspiration from the Material-3 design guide [specification](https://m3.material.io) and uses its values as defaults when it is possible to do so in Flutter SDK theming, still having its Material-2 design theming limitations. The component themes can be configured further by configuring a large number of properties in `FlexSubThemesData`, that is passed into `subThemesData`. A commonly used feature is to adjust the default corner border radius on all sub-themes for widgets that support it. Other opinionated changes include a more flat design, and features like primary tinted hover, focus, highlight and splash colors, among other things. For full list of component theme configuration options and some other related theme-modifying properties, please see the API docs for `FlexSubThemesData`. API reference: [**FlexSubThemesData**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData-class.html). ### FlexSubThemesData In addition to all the actual component theme configuration parameters, the `FlexSubThemesData` configuration has a few extra settings that are also used to control the behavior of the opinionated overall theme. * [**useTextTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData/useTextTheme.html): (true/false/**null**). Determines if Material-3 TextTheme and Typography is used. When opting in on using the sub-theming, this flag controls if the TextTheme use the new Material-3 `Typography.material2021` as specified in the [Material-3 Design Guide](https://m3.material.io). * If not defined, and `ThemeData.useMaterial3` is true, then it defaults to true. If not defined and `ThemeData.useMaterial3` is false, then it defaults to false. * This toggle works as an override toggle for using `Typography.material2021` in Material-2 mode and for using `Typography.material2018` in Material-3 mode. * When using **FlexColorScheme** and `ThemeData.useMaterial3` is false and sub themes are not used, then default typography is `Typography.material2018`. Note that if FlexColorScheme is not used at all, and your `ThemeData` has `ThemeData.useMaterial3` false, then Flutter defaults to using very old poor `Typography.material2014`. In such cases consider defining your typography manually to `Typography.material2018` or why not even `Typography.material2021`. FlexColorScheme fully supports using any custom TextTheme and fonts, just like ThemeData. You apply and use them just as you would with ThemeData. This text theme is just a custom predefined TextTheme. If you specify a custom `typography` to `FlexColorScheme` or `FlexThemeData`, this property has no impact on used typography. * This property was originally used in `FlexColorScheme` to opt-in on using a custom text theme defined internally by `FlexColorScheme` to look like the typography and text theme used in Material-3, before such a text theme and typography existed in Flutter. When Flutter started providing M3 text theme and typography, this property was converted into toggle to opt in and out of using the text theme. Typically, you do not want to opt-out of it, but in M2 mode you may want to opt-in and set it to true. * [**blendTextTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData/blendTextTheme.html): (true/**false**). Used blend primary color into text themes for both `ThemeData.textTheme` and `ThemeData.primaryTextTheme`. The strength of the blend is affected by the general `blendLevel` of used FlexColorScheme. This feature does not look so good if you need to put text on a completely different colored container than the background color. If this is your use case, consider setting it to false. * [**blendOnLevel**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData/blendOnLevel.html): (int: **0**). Sets the blend level strength of container color, used in its onColor. Use `blendOnLevel` value to in FlexColorScheme themes to also blend in each corresponding `ColorScheme` color property's color into its onColors. If `blendOnColors` is false, the `blendOnLevel` setting only affects `onSurface`, `onBackGround`, `onPrimaryContainer`, `onSecondaryContainer` `onTertiaryContainer` and `onErrorContainer`. If `blendOnColors` is true, it also impacts `onPrimary`, `onSecondary`, `onTertiary` and `onError`. * [**blendOnColors**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData/blendOnColors.html): (**true**/false). Set to true to enable `blendOnLevel` based onColor blending also on `onPrimary`, `onSecondary` and `onTertiary` colors. Use `blendOnLevel` value to in FlexColorScheme themes to also blend in each corresponding `ColorScheme` color property's color into its onColors. If `blendOnColors` is false, the `blendOnLevel` setting only affects `onSurface`, `onBackGround`, `onPrimaryContainer`, `onSecondaryContainer` `onTertiaryContainer` and `onErrorContainer`. If `blendOnColors` is true, it also impacts `onPrimary`, `onSecondary`, `onTertiary` and `onError`. * [**interactionEffects**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData/interactionEffects.html): (**true**/false). Flag used to enable color tinted hover, focus, highlight, selected, pressed and splash interaction state effects. The standard Flutter colors in both M2 and M3 mode for hover, focus, highlight, selected, pressed and splash state effects often look grey. They typically use surface or onSurface color with opacity. Often this is white or black with different opacity levels. This is not very color expressive and sometimes even look out of character in M3 mode. * [**tintedDisabledControls**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData/tintedDisabledControls.html): (**true**/false). Set to true to make disabled controls use a slight color tint of their own main enabled color on their disabled state. Enabling this feature makes the theme even more color expressive than Material-3 is by default. **Example: FlexColorScheme with SubThemes** A very practical use case of `FlexSubThemes`, is to customize the 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, the [`defaultRadius`](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemesData/defaultRadius.html). In this example, we enable the opinionated component themes and decided we want all our components that have adjustable border radius, to use 12 dp as their border radius. We also turned off the M3 text theme and set onColors in light mode to use blend level 20, and no blends on `onPrimary`, `onSecondary`, `onTertiary` and `onError`. In dark mode we wanted a stronger blend on the onColors, and we wanted in on all onColors and left `blendOnColors` to its default `true`value. Otherwise, we use the same property values as in the previous example. ```dart theme: FlexThemeData.light( scheme: FlexScheme.flutterDash, usedColors: 4, surfaceMode: FlexSurfaceMode.highScaffoldLowSurface, blendLevel: 20, appBarStyle: FlexAppBarStyle.background, appBarOpacity: 0.95, tabBarStyle: FlexTabBarStyle.forBackground, swapColors: true, subThemesData: const FlexSubThemesData( blendOnLevel: 20, blendOnColors: false, useTextTheme: false, defaultRadius: 12.0, ), keyColors: const FlexKeyColors( useSecondary: true, useTertiary: true, ), tones: FlexTones.vivid(Brightness.light), ), darkTheme: FlexThemeData.dark( scheme: FlexScheme.flutterDash, usedColors: 4, surfaceMode: FlexSurfaceMode.highScaffoldLowSurface, blendLevel: 15, appBarStyle: FlexAppBarStyle.background, appBarOpacity: 0.90, tabBarStyle: FlexTabBarStyle.forBackground, subThemesData: const FlexSubThemesData( blendOnLevel: 30, useTextTheme: false, defaultRadius: 12.0, ), keyColors: const FlexKeyColors( useSecondary: true, useTertiary: true, ), tones: FlexTones.vivid(Brightness.dark), ), ``` When we try the above `FlexThemeData` config, again in the [**Copy Playground**](/copy_playground) app, we get an application with this themed design:
[API sub 9](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-09-sub.png)   [API sub 10](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-10-sub.png)   [API sub 11](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-11-sub.png)   [API sub 12](https://raw.githubusercontent.com/rydmike/flex_color_scheme_docs/master/docs/images/fcs-v5-api-12-sub.png)
_The **Copy Playground** theme presentation app, with above FlexThemeData setup using component **subThemesData** and global border **defaultRadius** of 12 dp._
### FlexSubThemes When you opt in on using the component themes, the `FlexColorScheme.toTheme` method uses the passed in `FlexSubThemesData` configuration data object, that is passed in via `FlexColorScheme.subThemesData`, to create the component themes using the properties provided. In some cases, typically for older core related "legacy" component theme cases, the component themes are created directly in the `toTheme` method. However, in most cases separate static sub-theme helper functions from the `FlexSubThemes` class are used. Component themes that are currently only defined directly in the `toTheme` method, will be moved into the `FlexSubThemes` class as well in a future update. These `FlexSubThemes` component themes are currently available and used via their static helper functions, when `toTheme` creates `ThemeData`: API reference: [FlexSubThemes](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes-class.html). * [**buttonTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/buttonTheme.html). This theme controls the old deprecated Material buttons theme. The buttons are already deprecated and will be removed in the next version of Flutter SDK. This theme is also going away in Flutter and will be deprecated in the next version of FlexColorScheme too. * [**bottomNavigationBar**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/bottomNavigationBar.html) used to create the component theme for the [BottomNavigationBar](https://api.flutter.dev/flutter/material/BottomNavigationBar-class.html) widget. * [**bottomSheetTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/bottomSheetTheme.html) used to create the component theme for the [BottomSheet](https://api.flutter.dev/flutter/material/BottomSheet-class.html) widget. * [**cardTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/cardTheme.html) used to create the component theme for the [Card](https://api.flutter.dev/flutter/material/Card-class.html) widget. * [**checkboxTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/checkboxTheme.html) used to create the component theme for the [Checkbox](https://api.flutter.dev/flutter/material/Checkbox-class.html) widget, also applies to check boxes used by the [CheckBoxListTile](https://api.flutter.dev/flutter/material/CheckboxListTile-class.html). * [**chipTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/chipTheme.html) used to create the component theme for the [Chip](https://api.flutter.dev/flutter/material/Chip-class.html) widget and related chips like [InputChip](https://api.flutter.dev/flutter/material/InputChip-class.html), [ChoiceChip](https://api.flutter.dev/flutter/material/ChoiceChip-class.html), [FilterChip](https://api.flutter.dev/flutter/material/FilterChip-class.html) and [ActionChip](https://api.flutter.dev/flutter/material/ActionChip-class.html). * [**dialogTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/dialogTheme.html) used to create the component theme for [Dialog](https://api.flutter.dev/flutter/material/Dialog-class.html) widgets. * [**elevatedButtonTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/elevatedButtonTheme.html) used to create the component theme for the [ElevatedButton](https://api.flutter.dev/flutter/material/ElevatedButton-class.html) widget. * [**floatingActionButtonTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/floatingActionButtonTheme.html) used to create the component theme for the [FloatingActionButton](https://api.flutter.dev/flutter/material/FloatingActionButton-class.html) widget. * [**inputDecorationTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/inputDecorationTheme.html) used to create the component theme for [InputDecoration](https://api.flutter.dev/flutter/material/InputDecoration-class.html) configuration that describes the style of [TextField](https://api.flutter.dev/flutter/material/TextField-class.html) and [InputDecorator](https://api.flutter.dev/flutter/material/InputDecorator-class.html). * [**navigationBarTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/navigationBarTheme.html) used to create the component theme for the Material-3 [NavigationBar](https://api.flutter.dev/flutter/material/NavigationBar-class.html) widget. * [**navigationRailTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/navigationRailTheme.html) used to create the component theme for the [NavigationRail](https://api.flutter.dev/flutter/material/NavigationRail-class.html) widget. * [**outlinedButtonTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/outlinedButtonTheme.html) used to create the component theme for the [OutlinedButton](https://api.flutter.dev/flutter/material/OutlinedButton-class.html) widget. * [**popupMenuTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/popupMenuTheme.html) used to create the component theme for the [PopupMenuButton](https://api.flutter.dev/flutter/material/PopupMenuButton-class.html) widget. * [**radioTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/radioTheme.html) used to create the component theme for the [Radio](https://api.flutter.dev/flutter/material/Radio-class.html) widget. * [**sliderTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/sliderTheme.html) used to create the component theme for the [Slider](https://api.flutter.dev/flutter/material/Slider-class.html) widget. * [**snackBarTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/snackBarTheme.html) used to create the component theme for the [SnackBar](https://api.flutter.dev/flutter/material/SnackBar-class.html) widget. * [**switchTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/switchTheme.html) used to create the component theme for the [Switch](https://api.flutter.dev/flutter/material/Switch-class.html) widget. * [**textButtonTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/textButtonTheme.html) used to create the component theme for the [TextButton](https://api.flutter.dev/flutter/material/TextButton-class.html) widget. * [**timePickerTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/timePickerTheme.html) used to create the component theme for the [TimePickerDialog](https://api.flutter.dev/flutter/material/TimePickerDialog-class.html) widget. * [**toggleButtonsTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/toggleButtonsTheme.html) used to create the component theme for the [ToggleButtons](https://api.flutter.dev/flutter/material/ToggleButtons-class.html) widget. * [**tooltipTheme**](https://pub.dev/documentation/flex_color_scheme/latest/flex_color_scheme/FlexSubThemes/tooltipTheme.html) used to create the component theme for the [Tooltip](https://api.flutter.dev/flutter/material/Tooltip-class.html) widget. You can also use these static component theme helpers without using FlexColorScheme to define custom components themes, or even without using FlexColorScheme at all. You can further modify the component theme helpers' produced results by using their `copyWith` method. These helpers may sometimes be simpler to use than the raw component theme constructors. You can also study them to see how some component theme that interests you is defined. ### Theme Extensions In version 5.1.0, FlexColorScheme added direct support for theme extensions to its API. You use it the same way as you use it with `ThemeData`. The default example, "The Hot Reload Playground" includes a simple demonstration of how to use it. In this example, it is only used to add a single extra theme color, that is used to give the heading a color based on this theme extension color. With theme extensions, you can add as many colors and other theme properties as you need, and you can add multiple different **ThemeExtension** subclasses as well. ```dart /// A theme Extension example with a single custom brand color property. class BrandTheme extends ThemeExtension { const BrandTheme({ this.brandColor, }); final Color? brandColor; // You must override the copyWith method. @override BrandTheme copyWith({ Color? brandColor, }) => BrandTheme( brandColor: brandColor ?? this.brandColor, ); // You must override the lerp method. @override BrandTheme lerp(ThemeExtension? other, double t) { if (other is! BrandTheme) { return this; } return BrandTheme( brandColor: Color.lerp(brandColor, other.brandColor, t), ); } } // Custom const theme with our brand color in light mode. const BrandTheme lightBrandTheme = BrandTheme( brandColor: Color.fromARGB(255, 8, 79, 71), ); // Custom const theme with our brand color in dark mode. const BrandTheme darkBrandTheme = BrandTheme( brandColor: Color.fromARGB(255, 167, 227, 218), ); ``` The `lightBrandTheme` is then added to our light theme via `FlexThemeData.light`, like so: ```dart class _DemoAppState extends State { ThemeMode themeMode = ThemeMode.system; @override Widget build(BuildContext context) { return MaterialApp( theme: FlexThemeData.light( ... // Add all our custom theme extensions, in this case we only have one. extensions: >{ lightBrandTheme, }, ), ... ); ``` The same is done with the `darkBrandTheme` color in `darkTheme` with `FlexThemeData.dark`.