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
- The Flutter starter reads the theme into a
SpringThemeData: the layers oflightordark, the root,extendsand the theme's own keys, with every$reference resolved. This is the same in every app. - The palette is made by this starter's design: from
seed-color,scheme-variantandcontrastwith Material'sColorScheme.fromSeed, or Flutter's baseline when none is set, then the roles ofcolors.*over it (see The palette from a seed). - The
ThemeDatais made of the theme (toMaterial()), then each component undercomponents.*is applied to it. - The
ThemeCustomizerbeans change it, in@Order; aThemeDatabean namedthemeordarkThemetakes the place of the madelightordarktheme before them (see Themes in code). - The
MaterialThemesbean keeps the result, made once per theme, and theMaterialAppshows 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
- Themes: the properties every app shares
- The palette from a seed
- Density and ink
- Component themes
- Themes in code
- Design libraries