Themes from properties

In an app with this starter, every theme of spring.flutter.theme.* is also Material's ThemeData. The theme is written once, in the properties that every app shares (colors, typography, shapes, motion, background: see Themes), plus a few that only Material has. The starter makes the ThemeData of each theme, and MaterialApp, Theme.of(context) and every Material widget use it. Only what the properties set differs from Flutter's own Material 3 theme.

Why

A Material app usually builds its ThemeData in Dart: a ColorScheme, a TextTheme, a dozen component themes, once for light and once for dark. Here the same theme is configuration. A designer changes application.yml, a profile changes it per platform, a theme downloaded at run time changes it without a release, and the same file serves a Material app, a Cupertino app and an app without a design library.

Example

From the Theme Showcase Material app of the framework's examples:

# lib/resources/application.yml
spring:
  flutter:
    theme:
      active: system
      seed-color: '#3F51B5'
      scheme-variant: tonalSpot
      typography:
        font-family: Inter
        title-large: { weight: 600 }
      shape:
        medium: 16
      components:
        app-bar:
          center-title: true
          background-color: $colors.primary-container
        card:
          elevation: 2
      themes:
        dark:
          brightness: dark
        ocean:
          extends: light
          seed-color: teal
          scheme-variant: vibrant
          shape: { medium: 20, large: 28 }
          colors:
            secondary: '#0277BD'
          components:
            card: { elevation: level0 }
        ocean-night:
          extends: ocean
          brightness: dark
spring.flutter.theme.active=system
spring.flutter.theme.seed-color=#3F51B5
spring.flutter.theme.scheme-variant=tonalSpot
spring.flutter.theme.typography.font-family=Inter
spring.flutter.theme.typography.title-large.weight=600
spring.flutter.theme.shape.medium=16
spring.flutter.theme.components.app-bar.center-title=true
spring.flutter.theme.components.app-bar.background-color=$colors.primary-container
spring.flutter.theme.components.card.elevation=2
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.ocean.extends=light
spring.flutter.theme.themes.ocean.seed-color=teal
spring.flutter.theme.themes.ocean.scheme-variant=vibrant
spring.flutter.theme.themes.ocean.colors.secondary=#0277BD
spring.flutter.theme.themes.ocean-night.extends=ocean
spring.flutter.theme.themes.ocean-night.brightness=dark

Widgets read the theme as in any Material app:

final scheme = Theme.of(context).colorScheme;
final title = Theme.of(context).textTheme.titleLarge;
Card(color: scheme.surfaceContainerLow, child: Text('Ocean', style: title));

How a ThemeData is made

  1. The Flutter starter reads the theme into a SpringThemeData: the layers of light or dark, the root, extends and the theme's own keys, with every $ reference resolved. This is the same in every app.
  2. The palette is made by this starter's design: from seed-color, scheme-variant and contrast with Material's ColorScheme.fromSeed, or Flutter's baseline when none is set, then the roles of colors.* over it (see The palette from a seed).
  3. The ThemeData is made of the theme (toMaterial()), then each component under components.* is applied to it.
  4. The ThemeCustomizer beans change it, in @Order; a ThemeData bean named theme or darkTheme takes the place of the made light or dark theme before them (see Themes in code).
  5. The MaterialThemes bean keeps the result, made once per theme, and the MaterialApp shows it.

What comes from the Flutter starter

These parts are the Flutter starter's properties, the same in every app. This starter puts them where Material's theme has a place for them:

Theme property In the ThemeData
The 46 palette roles: colors.*, or made from the seed colorScheme, Material's ColorScheme with every role of the theme's palette
typography.font-family, typography.font-family-fallback fontFamily, fontFamilyFallback
The 15 text styles (display-large ... label-small) textTheme: a style the theme sets replaces Material's, the others stay Material's
shape.* No field of its own: the components that follow a token (cards medium, dialogs extra-large, buttons full, ...) take it when the theme changes that token, and a component's shape: large reads it (see components)
elevation.* A component's elevation: level2 reads the level
motion.page-transition pageTransitionsTheme, the same transition on every platform; with platform (or nothing set) Flutter's own per platform
background scaffoldBackgroundColor is transparent, so the background shows through every Scaffold
What Material has no place for: spacing, tokens, styles, the code style, animations, loaders The SpringThemeExtension among extensions (see below)

What this starter adds

Theme property In the ThemeData Page
seed-color, scheme-variant, contrast The palette Material 3 makes of them The palette from a seed
components.<name>.* About fifty component themes: cardTheme, appBarTheme, filledButtonTheme, inputDecorationTheme, ... Component themes
visual-density visualDensity Density and ink
tap-target-size materialTapTargetSize Density and ink
splash (one word) splashFactory Density and ink
motion.page-transition: zoom ZoomPageTransitionsBuilder, Material's zoom transition Motion

All of them also go inside a named theme (themes.<name>.components.card.*). seed-color, scheme-variant and contrast are calculated by the Cupertino starter too, with the same colors; the others are Material's alone.

Light, dark and system

light and dark always exist; spring.flutter.theme.active picks what is shown:

active The MaterialApp gets
system (the default) theme: the theme of system-light (default light), darkTheme: the theme of system-dark (default dark), themeMode: ThemeMode.system. Material switches between them with the device
A theme's name theme: that theme, themeMode: ThemeMode.light. A dark theme is shown as it is, since its palette is dark

The ThemeSelection bean changes the choice at run time, and the app shows the new theme at once:

class ThemeMenu extends SpringStatelessWidget<(ThemeSelection,)> {
  const ThemeMenu({super.key});

  @override
  Widget build(BuildContext context) {
    final (selection,) = beans;
    return PopupMenuButton<String>(
      onSelected: selection.select,
      itemBuilder: (_) => [
        for (final name in ['system', 'light', 'dark', 'ocean'])
          PopupMenuItem(value: name, child: Text(name)),
      ],
    );
  }
}

See Themes for system-light, system-dark, remember and extends.

Themes loaded at run time

A theme can arrive after the start: from a URL in the properties (themes.<name>.source, see a theme from a URL), or from code with the SpringThemes bean:

@Service()
class WinterThemes {
  WinterThemes(this.themes, this.selection);

  final SpringThemes themes;
  final ThemeSelection selection;

  Future<void> show() async {
    themes.loadYaml(
      await http.read(Uri.parse('https://themes.example.com/winter.yml')),
    );
    selection.select('winter');
  }
}

A loaded theme is checked as the themes of the files are, Material's part too: an unknown component or a wrong value throws a ThemePropertyException and changes nothing. Then the MaterialThemes bean makes its ThemeData (with the customizers) when it is first shown.

The properties this starter reads

Key Values Default What it does
spring.flutter.theme.seed-color a color none The color the palette is made from
spring.flutter.theme.scheme-variant tonalSpot, fidelity, content, vibrant, expressive, monochrome, neutral, rainbow, fruitSalad tonalSpot How the palette is made from the seed
spring.flutter.theme.contrast -1 to 1 0 The contrast of the palette
spring.flutter.theme.components.<name>.* see the component reference Flutter's The theme of one Material component, by Flutter's property names in kebab case
spring.flutter.theme.visual-density adaptive, standard, comfortable, compact Flutter's per platform How densely Material's controls are packed
spring.flutter.theme.tap-target-size padded, shrink-wrap Flutter's per platform The minimum area a tap hits
spring.flutter.theme.splash ripple, sparkle, none Flutter's per platform The ink of a tap. A map under splash is something else: the splash screen of the start, which every app reads
spring.flutter.theme.motion.page-transition zoom Material's zoom transition; the other values are the Flutter starter's

Checked at the start

The starter reads its part of every theme when the application starts, not when a widget first needs it: an unknown component or property, a wrong value, or a combination Flutter refuses fails the start and names the property and the valid values, with a "did you mean" where one is close (the list is shortened here):

Invalid theme property spring.flutter.theme.components.crad (theme light): ''; expected a component: app-bar, badge, banner, ... (did you mean 'card'?).

A theme loaded at run time is checked the same way, before it replaces anything.

Without this starter

A theme may carry components, visual-density, tap-target-size and a single-value splash in an app without this starter: a theme library has them for the apps that use Material. There they are accepted, not shown and not checked, and one INFO line of the log tells each, once:

The theme property components is not shown and not checked: spring_boot_starter_flutter_material, which reads it, is not in the application.

The key is still checked: componets fails the start. SpringThemeData.unreadDesignProperties lists them, with the starter that reads each. seed-color, scheme-variant, contrast and the zoom transition are different: without a design starter they fail the start, naming it. In an app with both design starters, Material's properties are read and checked whatever the app's type. See Design libraries.

Reading the theme

Material's widgets read Theme.of(context). What Material's theme has no place for is in the SpringTheme, in every app:

final theme = SpringTheme.of(context);
final gap = theme.space('m');
final code = theme.textStyle('code');

Code that has only Material's ThemeData at hand (a ThemeData passed to a function, a widget below a Theme of its own) reaches it through the extension every made ThemeData carries:

final spring = Theme.of(context).extension<SpringThemeExtension>()!.data;
final gap = spring.space('s');

A theme other than the one shown, as Material's ThemeData, comes from the MaterialThemes bean, customized like the app's:

// In a widget: the bean, injected.
class OceanPreview extends SpringStatelessWidget<(MaterialThemes,)> {
  const OceanPreview({super.key});

  @override
  Widget build(BuildContext context) {
    final (themes,) = beans;
    return Theme(data: themes.theme('ocean'), child: const PreviewCard());
  }
}

// Outside a widget: from the application context.
final ocean = MaterialThemes.of(applicationContext).theme('ocean');

SpringThemeData.toMaterial() gives the ThemeData of one theme without the customizers, and materialColorScheme its palette as Material's ColorScheme.

In Spring (Java)

There is no counterpart: Spring has no themes for apps.

See also