When is the full textTheme available?

[jgarciamccausland]

Hello, I am trying to alter the global ListTile titleTextStyle and subtitleListStyle but I noticed that not all of the bodyLarge and bodyMedium TextStyle properties are available immediately. I am forced to manually include the default TextStyle properties in the .copyWith along with the ones I want to add. Is there a better way to implement this?

final applyLightTheme = FlexThemeData.light(
      useMaterial3: true,
      useMaterial3ErrorColors: true,
      appBarBackground: CustomColorsScheme.light.surface2,
      scaffoldBackground: CustomColorsScheme.light.background,
      surfaceTint: Colors.transparent,
      onSurface: CustomColorsScheme.light.onSurface,
      colors: const FlexSchemeColor(
        primary: Color(0xFF4B6620),
        secondary: Color(0xFF48574B),
        secondaryContainer: Color(0xFFC8D7CB),
        error: Color(0xFF662C29),
      ),
      extensions: const <ThemeExtension<dynamic>>[CustomColorsScheme.light],
    );

    print(applyLightTheme.textTheme.bodyLarge?.fontSize.toString()); // prints null

    _lightTheme = applyLightTheme.copyWith(
        listTileTheme: applyLightTheme.listTileTheme.copyWith(
          titleTextStyle: applyLightTheme.textTheme.bodyLarge, 
          subtitleTextStyle: applyLightTheme.textTheme.bodyMedium!.copyWith(color: CustomColorsScheme.light.onSurfaceVariant),
        ),
    );

[rydmike]

Hi @jgarciamccausland,

Thanks for your question. This is a good one, and it is a fairly common one for Flutter generally too, as it applies to it as well.

It is actually surprisingly complicated how and when the default text geometry is applied to all the TextStyles in textTheme and primaryTextTheme in ThemeData.of(context), but never to an object created by any ThemeData factory.

TLDR and short answer

As for using FlexColorScheme and when the full textTheme is available, the answer is simple.
It is the same as for any Flutter app using MaterialApp.

This means after the MaterialApp widget has been created and localization applied. The text themes in FlexColorScheme's created ThemeData work the same way as vanilla ThemeData and its factories. It does as you noticed not contain any geometry for any of the TextStyles in the textTheme or primaryTextTheme. It does however contain the correct/default contrast color for the light/dark theme mode and as defined for M2/M3 mode.

The long story and why it is this way

The font sizes in the ThemeData.of(context).textTheme and all its text styles, are not defined or applied when the ThemeData object is created by its factories. However, if you deconstruct the ThemeData.typography you will find the defaults that will be applied later there. They are in the englishLike, dense and tall properties. Which one it will be, depends on the user's locale.

The default text style sizes are applied by the static ThemeData of(BuildContext context) function:

https://github.com/flutter/flutter/blob/68e95b9e7ef8012325ed6d8ba1d8ad741d6f705b/packages/flutter/lib/src/material/theme.dart#L109

as shown here:

  static ThemeData of(BuildContext context) {
    final _InheritedTheme? inheritedTheme = context.dependOnInheritedWidgetOfExactType<_InheritedTheme>();
    final MaterialLocalizations? localizations = Localizations.of<MaterialLocalizations>(context, MaterialLocalizations);
    final ScriptCategory category = localizations?.scriptCategory ?? ScriptCategory.englishLike;
    final ThemeData theme = inheritedTheme?.theme.data ?? _kFallbackTheme;
    return ThemeData.localize(theme, theme.typography.geometryThemeFor(category));
  }

The category picks up the geometry used by the locale from localizations with default fallback to englishLike. There are 3 categories described by the enum ScriptCategory.

https://github.com/flutter/flutter/blob/5a6a3224fe1502dc2f1f05c13268f3e96bc89461/packages/flutter/lib/src/material/typography.dart#L26

/// A characterization of the of a [TextTheme]'s glyphs that is used to define
/// its localized [TextStyle] geometry for [ThemeData.textTheme].
///
/// The script category defines the overall geometry of a [TextTheme] for
/// the [Typography.geometryThemeFor] method in terms of the
/// three language categories defined in <https://material.io/go/design-typography>.
///
/// Generally speaking, font sizes for [ScriptCategory.tall] and
/// [ScriptCategory.dense] scripts - for text styles that are smaller than the
/// title style - are one unit larger than they are for
/// [ScriptCategory.englishLike] scripts.
enum ScriptCategory {
  /// The languages of Western, Central, and Eastern Europe and much of
  /// Africa are typically written in the Latin alphabet. Vietnamese is a
  /// notable exception in that, while it uses a localized form of the Latin
  /// writing system, its accented glyphs can be much taller than those
  /// found in Western European languages. The Greek and Cyrillic writing
  /// systems are very similar to Latin.
  englishLike,

  /// Language scripts that require extra line height to accommodate larger
  /// glyphs, including Chinese, Japanese, and Korean.
  dense,

  /// Language scripts that require extra line height to accommodate
  /// larger glyphs, including South and Southeast Asian and
  /// Middle-Eastern languages, like Arabic, Hindi, Telugu, Thai, and
  /// Vietnamese.
  tall,
}

Which one gets used depends on the user's locale. These are defined for each locale in the flutter_localizations package, in each locale's .arb file using the "scriptCategory" property.

From the ThemeData and its typography property instance, the method geometryThemeFor in theme.typography.geometryThemeFor(category) picks up the corresponding geometry from the typography, that was already added by the used ThemeData factory or FlexThemeData.

Finally, the last line's ThemeData.localize does the magic by doing this:

https://github.com/flutter/flutter/blob/d5ac6c46ed8f61caca041e0f94ba0cc420a8b5db/packages/flutter/lib/src/material/theme_data.dart#L1744

  /// Returns a new theme built by merging the text geometry provided by the
  /// [localTextGeometry] theme with the [baseTheme].
  ///
  /// For those text styles in the [baseTheme] whose [TextStyle.inherit] is set
  /// to true, the returned theme's text styles inherit the geometric properties
  /// of [localTextGeometry]. The resulting text styles' [TextStyle.inherit] is
  /// set to those provided by [localTextGeometry].
  static ThemeData localize(ThemeData baseTheme, TextTheme localTextGeometry) {
    // WARNING: this method memoizes the result in a cache based on the
    // previously seen baseTheme and localTextGeometry. Memoization is safe
    // because all inputs and outputs of this function are deeply immutable, and
    // the computations are referentially transparent. It only short-circuits
    // the computation if the new inputs are identical() to the previous ones.
    // It does not use the == operator, which performs a costly deep comparison.
    //
    // When changing this method, make sure the memoization logic is correct.
    // Remember:
    //
    // There are only two hard things in Computer Science: cache invalidation
    // and naming things. -- Phil Karlton

    return _localizedThemeDataCache.putIfAbsent(
      _IdentityThemeDataCacheKey(baseTheme, localTextGeometry),
      () {
        return baseTheme.copyWith(
          primaryTextTheme: localTextGeometry.merge(baseTheme.primaryTextTheme),
          textTheme: localTextGeometry.merge(baseTheme.textTheme),
        );
      },
    );
  }

Basically merging in the locale based text style geometries for the ThemeData that will later be returned by Theme.of(context) when you use it. So it basically creates a new textTheme and primaryTextTheme based on the localized text geometry. This is why, it is not available in a ThemeData object created e.g, by ThemeData, ThemeData.from, FlexThemeData.light/dark or FlexColorScheme.light/dark().toTheme. ThemeData does not know about the locale that will be used by the context.

In the MaterialApp, this new localized theme is then inserted into the widget tree via an AnimatedTheme widget, that inserts it as a Theme widget with the new inherited ThemeData.

https://github.com/flutter/flutter/blob/d5ac6c46ed8f61caca041e0f94ba0cc420a8b5db/packages/flutter/lib/src/material/app.dart#L938

    return ScaffoldMessenger(
      key: widget.scaffoldMessengerKey,
      child: DefaultSelectionStyle(
        selectionColor: effectiveSelectionColor,
        cursorColor: effectiveCursorColor,
        child: AnimatedTheme(
          data: theme,
          duration: widget.themeAnimationDuration,
          curve: widget.themeAnimationCurve,
          child: widget.builder != null
            ? Builder(
                builder: (BuildContext context) {
                  // Why are we surrounding a builder with a builder?
                  //
                  // The widget.builder may contain code that invokes
                  // Theme.of(), which should return the theme we selected
                  // above in AnimatedTheme. However, if we invoke
                  // widget.builder() directly as the child of AnimatedTheme
                  // then there is no Context separating them, and the
                  // widget.builder() will not find the theme. Therefore, we
                  // surround widget.builder with yet another builder so that
                  // a context separates them and Theme.of() correctly
                  // resolves to the theme we passed to AnimatedTheme.
                  return widget.builder!(context, child);
                },
              )
            : child ?? const SizedBox.shrink(),
        ),
      ),
    );
  }

Yes, I agree, the process used to apply the default text style geometry to all TextStyles in textTheme and primaryTextTheme in Flutter's ThemeData is very complex. Sadly FlexColorScheme cannot really do much about that.

Options?

If you want to use sizes from the Theme.of(context).textTheme based on its default sizes, in custom component themes, you have to wrap your app with an extra Theme widget after the MaterialApp. Then, there extract the sizes or text styles you need, and add them back into each component theme where you want to use it, by using copyWith for the new inherited ThemeData in the Theme wrapper. It is not difficult, but it gets a bit involved and tedious to set it up.

Optionally, if you do know you will only use e.g. a locale where the englishLike geometry is used, then you can extract the sizes from e.g your myThemeData, ThemeData object (defined with vanilla ThemeData() or FlexThemeData.light/dark()) by grabbing a desired size e.g. from myThemeData.typography.englishLike.bodyLarge.fontSize, even before you have created the MaterialApp. Then create a new ThemeData with component theme's using the desired font sizes added in, and then use that as ThemeData in the MaterialApp.theme. I must admit I have never done this, but it might be a useful little shortcut for some use cases.

INFO: FlexColorScheme also contains ways to extract the effective resulting ColorScheme it will produce, before you return the ThemeData. This way you can use the colors from its ColorScheme also in custom component themes added with copyWith directly on the toTheme, thus saving one step. This is described in the docs here https://docs.flexcolorscheme.com/api_guide#use-flexcolorscheme-or-flexthemedata.

The way I usually do custom sizes for component themes is via custom TextStyles and custom TextTheme.

Custom TextTheme and TextStyles

If you do provide a custom TextTheme, complete with geometry to the textTheme property in FlexColorScheme or vanilla ThemeData, then you can use this TextTheme's fontSizes directly also in custom component themes.

Likewise, if you define custom TextStyles with geometry, you can use them in component theme's TextStyles directly. In component themes, it is typically enough to just define the TextStyle(fontSize: mySize), if that is all you want to change.

Using a full custom textTheme in ThemeData is discussed and demonstrated with one example at the end of the answer in this question: #160, that also contains other useful info about Flutter's TextTheme and GoogleFonts.

I am referring to this at the end of the answer:

final TextStyle openSansRegular =
    GoogleFonts.openSans(fontWeight: FontWeight.w400);
final TextStyle openSansMedium =
    GoogleFonts.openSans(fontWeight: FontWeight.w500);
final TextStyle openSansBold =
    GoogleFonts.openSans(fontWeight: FontWeight.w700);

final TextTheme customOpenSansTextTheme = TextTheme(
  displayLarge:
      openSansBold.copyWith(fontSize: 50), // Custom bold and size (Regular is default)
  displayMedium: openSansRegular, // Regular is default
  displaySmall: openSansRegular, // Regular is default
  headlineLarge: openSansRegular, // Regular is default
  headlineMedium: openSansRegular, // Regular is default
  headlineSmall: openSansRegular, // Regular is default
  titleLarge: openSansBold, // Custom bold (Regular is default)
  titleMedium: openSansBold, // Custom bold (Medium is default)
  titleSmall: openSansBold, // Custom bold (Medium is default)
  bodyLarge: openSansRegular, // Regular is default
  bodyMedium: openSansRegular, // Regular is default
  bodySmall: openSansRegular, // Regular is default
  labelLarge: openSansBold, // Custom bold (Medium is default)
  labelMedium: openSansBold, // Custom bold (Medium is default)
  labelSmall: openSansMedium, // Medium is default
);

Instead, of just defining the three text styles with regular, medium and bold, you could define one for every TextStyle in the TextTheme and also give each one of them the desired fontSize. Any font sizes you have predefined in the passed in custom TextTheme and its TextStyles will be kept when the final ThemeData is created and localized.

If you leave the color out of the text styles, the ThemeData defaults (for light/dark mode and M2/M3 mode) will be used. If you add colors, you will have to add correct (desired) ones separately for light and dark mode.

INFO: GoogleFonts returned text themes contain a bug where they hard code the font color to white, making using the TextThemes returned by GoogleFonts very complicated in a ThemeData factory. See issue: material-foundation/flutter-packages#401. A workaround example is provided in the issue.

With the above discussed setup, you can use each style with its size in any component theme TextStyle property, just as you can use any other custom TextStyle you create.

If you want a custom TextStyle to also lerp animate its colors (theme mode light/dark changes) and font size changes, if it is not constant (eg in text content/style editor). You can add them as ThemeExtensions, then changes to them will animate when you change their property values.

You can find an example of that in the Theming workshop from the Flutter'N Friends conference in Stockholm. Repo is here https://github.com/rydmike/theming_workshop/tree/31-done and here is a theme extension with custom TextStyless https://github.com/rydmike/theming_workshop/blob/31-done/lib/workshop/theme/avo_theme_ext.dart.

The workshop also demonstrates the usage of the fixColors extension to work around the mentioned GoogleFonts hard coded default white text color, so it that fixes the TextThemes it returns and you get theme mode correct contrast colors on the text theme via ThemeData. See https://github.com/rydmike/theming_workshop/blob/31-done/lib/workshop/utils/utils.dart and https://github.com/rydmike/theming_workshop/blob/fad4dec4b53e5738d598d99a0351d6925f37910c/lib/workshop/theme/avo_theme.dart#L350

NOTE: FlexColorScheme, will detect if you have applied a full TextTheme returned by GoogleFonts to textTheme or primaryTextTheme in FlexThemeData/FlexColorScheme and include the contrast color fix automatically. It also fixes the in some cases incorrect primaryTextTheme contrast color produced by ThemeData in dark mode, see flutter/flutter#118146.

Hope this helps! 💙

Yes, TextTheme is a bit complex in Flutter 😄

[jgarciamccausland]

Hi @rydmike!

First of all, wow! Thank you very much for the detailed answer. Your knowledge depth is very impressive.

We were manually applying TextStyles to almost every Text widget instead of utilizing the default styling provided by its parent (or itself). In an attempt to clean up our codebase, we realized our themes were not set up for the outcome we desired.

We were able to resolve our primary issue (of not having the desired text color for the title and subtitle texts in ListTiles) by utilizing the colorScheme property in FlexThemeData.light and FlexThemeData.dark when initializing our themes (replacing what I posted in the discussion opener). This also ended up resolving other color-related issues we were encountering and sets us up nicely going forward.

    final colorSchemeLight = ColorScheme(
      brightness: Brightness.light,
      primary: CustomColorsScheme.light.primary!,
      onPrimary: CustomColorsScheme.light.onPrimary!,
      secondary: CustomColorsScheme.light.secondary!,
      onSecondary: CustomColorsScheme.light.onSecondary!,
      secondaryContainer: CustomColorsScheme.light.secondaryContainer!,
      onSecondaryContainer: CustomColorsScheme.light.onSecondaryContainer,
      error: CustomColorsScheme.light.error!,
      onError: CustomColorsScheme.light.onErrorContainerHigh!,
      background: CustomColorsScheme.light.background!,
      onBackground: CustomColorsScheme.light.onBackground!,
      surface: CustomColorsScheme.light.surface!,
      onSurface: CustomColorsScheme.light.onSurface!,
      surfaceVariant: CustomColorsScheme.light.surfaceVariant!,
      onSurfaceVariant: CustomColorsScheme.light.onSurfaceVariant!,
      outline: CustomColorsScheme.light.outline,
      outlineVariant: CustomColorsScheme.light.outlineVariant,
      inverseSurface: CustomColorsScheme.light.inverseSurface!,
      inversePrimary: CustomColorsScheme.light.inversePrimary!,
      surfaceTint: Colors.transparent,
    );

    final flexThemeLight = FlexThemeData.light(
      colorScheme: colorSchemeLight,
      useMaterial3: true,
      useMaterial3ErrorColors: true,
      appBarBackground: CustomColorsScheme.light.surface2,
      extensions: const <ThemeExtension<dynamic>>[CustomColorsScheme.light],
    );

Then overriding any properties defaults we wanted to alter using flexThemeLight.copyWith.

Again, thank you very much for the insight into TextTheme and TextStyle and the options provided. I will definitely be checking out the Theming workshop.

[rydmike]

Thanks @jgarciamccausland!

And yes, if you predefine your colors, e.g. in a ColorScheme like you did above, you can indeed use them as overrides by using copyWith.

Be aware of two things though if you pass in a complete ColorScheme and generally when you use copyWith.

1. FlexColorScheme may make a new different ColorScheme

If you use an input colorScheme, some modifiers in FlexColorScheme APIs may modify the produced effective ColorScheme of the theme, so the colorScheme you pass in may not be equal to the one produced and used by your main app theme, so the corresponding colors in the ColorScheme you passed may thus not match the same colors in the Theme.of(context).colorScheme.

This happens if you use blend levels higher than 0, seed generated color scheme, color input limiter and color swappers or force material 3 error colors. Basically effects that modify the input colors or color scheme. Your example above is not using them, except one, so you are mostly fine.

The colors in the input ColorScheme are still the same as the ones that will be produced and used to make the theme. Except for the error colors, you are forcing them to be the Material-3 defaults with useMaterial3ErrorColors: true the ones you provide via your custom color scheme colorSchemeLight are not used, unless they happen to match M3 error colors.

Produced ColorScheme modifier effect properties are:

  usedColors: 5,
  surfaceMode: FlexSurfaceMode.levelSurfacesLowScaffold,
  blendLevel: 7,
  swapColors: true,
  useMaterial3ErrorColors: true,
  keyColors: const FlexKeyColors(),
  tones: FlexTones.candyPop(Brightness.light).onSurfacesUseBW().surfacesUseBW(),

If you use built-in component sub-theming with FlexColorScheme or FlexThemeData, there are a few more such modifiers:

  subThemesData: const FlexSubThemesData(
    blendOnLevel: 10,
    blendOnColors: true,
    blendTextTheme: true,
  ),

So if I add all these modifiers, to your theme example, with your custom input color scheme, you would have e.g.

final FlexColorScheme flexSchemeLight = FlexColorScheme.light(
  colorScheme: colorSchemeLight,
  useMaterial3: true,
  useMaterial3ErrorColors: true,
  appBarBackground: CustomColorsScheme.light.surface2,
  usedColors: 5,
  surfaceMode: FlexSurfaceMode.levelSurfacesLowScaffold,
  blendLevel: 7,
  swapColors: true,
  keyColors: const FlexKeyColors(),
  subThemesData: const FlexSubThemesData(
    blendOnLevel: 10,
    blendOnColors: true,
    blendTextTheme: true,
  ),
  tones: FlexTones.candyPop(Brightness.light).onSurfacesUseBW().surfacesUseBW(),
  extensions: const <ThemeExtension<dynamic>>[CustomColorsScheme.light],
);

The effective ColorScheme above that gets used by the resulting theme, would be very different from the input colorScheme, as it used many modifiers.

Notice above that I used FlexColorScheme.light, this is one step before FlexColorScheme makes ThemeData, basically just the blueprint for it, it creates a FlexColorScheme object.

With it you can extract the ColorScheme it will make when it makes a theme.

final ColorScheme scheme = flexSchemeLight.toScheme;

That ColorScheme will contain the exact colors that the theme will get when all modifiers have been applied. If you use the colors from it, for component themes or text themes, you can be sure it is the same colors as used in your theme's colorScheme.

final ThemeData flexThemeLight = flexSchemeLight.toTheme.copWith( ...
  // Add changes here using colors from 'scheme' above,
  // they will be the same as the colors FlexColorScheme uses to make the 
  // ThemeData when you use toTheme, or if you would have used FlexThemeData.light.
)

This is what is described here https://docs.flexcolorscheme.com/api_guide#use-flexcolorscheme-or-flexthemedata too.

If you require more colors than those that fit into a standard ColorScheme, often semantic colors, then adding them as theme extensions is the way to go, like you have done 👍🏻

2. Component themes may not be null

When you override your FlexColorScheme.light/dark().toTheme or FlexThemeData.light/dark() created ThemeData object and its component themes with copyWith, be aware that FlexColorScheme may already have made some changes to many properties in some component themes, so the component themes may no longer have all null props, like a ThemeData made without component theme definitions normally would have.

If you do not want to loose these changes, you must first copy the component theme from the produced ThemeData, eg from your flexThemeLight light above, then apply the changes on that component theme with its copyWith to make a new version of that component theme, then use copyWith on the flexThemeLight, copying in that full new version of said component theme.

If you just use the component theme's constructor directly with the ThemeData.copyWith and there setting the prop you want to change, you would loose any other props FlexColorScheme had already defined for it.

This is of course just normal nested immutable object copyWith behavior, but it can be good to mention it.

There are a few Q&A's around here in discussions that demonstrates this. Here is one #41.

Also even if you do not use subThemesData: const FlexSubThemesData(), to activate making a lot of custom component theming with FlexColorScheme, in you example above you had not done so. FlexColorScheme will create a few component themes anyway to modify a few things, what it does by default is described here: https://docs.flexcolorscheme.com/core_defaults#core-component-themes as well as which ones will be none null.

If you do activate component themes, then a lot more component themes get definitions and are no longer all null props (that is they are null results in Flutter default designs being used for each component theme property that is null). As explained here https://docs.flexcolorscheme.com/core_defaults#core-component-themes. Which component themes and props in them, gets prop values, depends on what you configure of course.

Typically, I do see that devs that use FlexColorScheme also do use the component themes. They are quite convenient and also offer some unique styling features and even platform adaptive themes. For most component themes it allows you to easily select what ColorScheme color is used for what part in each widget and adjust other key props and style easily too.

It has a lot of APIs, but since you can use the Themes Playground to define the theme visually, see what API code configs it makes as you change things, and of course just copy/paste the FlexColorScheme code it wrote, I typically see it being used a lot for experimenting with theme and different designs.