Flutter themes in YAML
With spring_boot_starter_flutter the look of an app lives in configuration,
not in ThemeData code. You write colors, fonts, shapes, component styles,
backgrounds and animations under spring.flutter.theme in application.yml.
The starter reads them when the app starts into a theme of its own
(SpringThemeData: the palette, the type scale, spacing, shapes, tokens,
styles, backgrounds, motion), which every app has, one without a design
library too. With a design starter the same theme also becomes Material's
ThemeData (spring_boot_starter_flutter_material)
or Cupertino's CupertinoThemeData
(spring_boot_starter_flutter_cupertino).
Designers can change the look in one file, per profile or per platform,
without touching widgets.
A first theme
spring:
flutter:
theme:
colors:
primary: '#0057B8'
on-primary: '#FFFFFF'
surface: '#FAFAFA'
typography:
font-family: Inter
title-large: { weight: 600 }
shape:
medium: 16
spacing:
m: 16
That is a complete theme, and it works in every app: one without a design library, a Material app and a Cupertino app. Everything you do not write keeps Flutter's Material 3 default: the roles you do not set come from Flutter's baseline palette, the text styles you do not set keep Material 3's type scale. A theme without any property is Flutter's own baseline.
Design libraries
spring_boot_starter_flutter knows no design library. What every design
shares (the palette roles, typography, shapes, spacing, tokens, styles,
motion, backgrounds, loaders, images) is on these pages. What belongs to one
design is documented with its starter:
- Material, with spring_boot_starter_flutter_material:
each theme becomes Material's
ThemeData; a palette from one seed color, the component themes undercomponents.*, density and ink, and themes in code. - Cupertino, with spring_boot_starter_flutter_cupertino:
each theme becomes Cupertino's
CupertinoThemeData, with the Cupertino theme properties undercupertino.*, and the same palette from a seed.
With a design starter, the first theme can be shorter: a seed makes all 46 roles.
spring:
flutter:
theme:
seed-color: deepPurple # needs a design starter
typography:
font-family: Inter
The examples of these pages that use a seed-color are for an app with a
design starter; an app without one writes its roles under colors.* (see
colors and design libraries).
Every value is checked at start. A misspelled key, a color that does not
exist or a number where a word is expected stops the start with a message that
names the property, the value and what is allowed, often with a "did you mean".
Nothing is ignored silently. The properties of a design whose starter is not
in the app (components, cupertino, and the others listed in
properties of a design) are accepted,
not checked, and named once in the log.
How a theme is chosen
There are three parts:
- The root of
spring.flutter.themeis shared by every theme. lightanddarkalways exist. Writethemes.lightorthemes.darkto change only what differs in them.- Any number of themes of your own live under
themes.<name>. Each one holds only what it changes.
spring:
flutter:
theme:
active: system # system, or the name of a theme
system-light: light # what "system" shows in light mode
system-dark: dark # what "system" shows in dark mode
seed-color: deepPurple # shared by every theme
themes:
dark:
seed-color: deepPurple.shade200
ocean:
seed-color: teal
scheme-variant: vibrant
ocean-night:
extends: ocean # start from ocean, not from the root
brightness: dark
| Key | Where | What it does |
|---|---|---|
active |
root | The theme shown at start. system (the default) follows the device's light or dark mode |
system-light |
root | The theme system shows when the device is in light mode. Default light |
system-dark |
root | The theme system shows when the device is in dark mode. Default dark |
remember |
root | Keeps the theme the user chooses between runs and shows it again while the splash shows. Default true |
themes.<name> |
root | A theme of your own, or a change to light or dark |
extends |
in themes.<name> |
Starts the theme from another theme instead of the root. Chains work; a cycle or an unknown name stops the start |
A theme is made in layers, each over the one before:
- its brightness (
darkfor thedarktheme, otherwiselight), - the root, or the theme it
extends, - its own keys.
A list in a later layer replaces the whole list of an earlier one. References
($colors.primary) are resolved after the layers are put together, so a theme
that changes colors.primary also changes everything that refers to it. See
tokens and references.
Theme names and property names are compared without case, - and _.
seed-color, seedColor and seed_color are the same key, and Ocean-Night
and ocean_night are the same theme.
Choosing and switching at run time
The ThemeSelection bean holds the choice. A settings page calls select
and the whole app changes at once.
selection.select('ocean'); // a theme
selection.select('system'); // follow the device again
The choice is kept between runs (remember: true, the default): ThemeSelection
writes it into the app's files, and the next start shows it again while the
splash shows, so a reload does not flash the default theme. A ThemeChoiceStore
bean keeps it elsewhere, such as an account's settings on a server. Themes can
also arrive at run time: themes.loadYaml(yaml) adds YAML from a server, and a
theme can be downloaded from a URL by itself (see
properties).
Read the theme in Dart
SpringTheme.of(context) has the whole theme, in an app of any type:
final theme = SpringTheme.of(context);
Container(
padding: EdgeInsets.all(theme.space('m')),
color: theme.colorScheme.surfaceContainer,
child: Text(isbn, style: theme.textStyle('code')),
);
A design library's widgets read the theme in their own form: Material's from
Theme.of(context) (see themes from properties),
Cupertino's from CupertinoTheme.of(context).
Typed keys: context.theme
The build generator reads your properties and writes
lib/spring_gen/theme.spring.keys.dart. From it, context.theme has a getter for
every key you declare, so a renamed property is a compile error and not a
surprise at run time:
context.theme.colors.surfaceContainerLow; // Color
context.theme.spacing.m; // double
context.theme.typography.titleLarge; // TextStyle
context.theme.tokens.brand.accent; // Color
context.theme.styles.neonChip; // AppStyleNeonChip, for ThemeStates
context.theme.motion.fast; // Duration
context.theme.motion.curves.out; // Curve
context.theme.animations.borderSpin; // AnimationSpec
context.theme.background; // ThemeBackgroundData?
AppThemes.ocean; // 'ocean', for ThemeSelection.select
Run dart run build_runner build after you add a key. The getters read the
theme that is shown when they are called, so a theme switch gives the new
values and the widget rebuilds. Only keys you declare are generated; the
roles computed from the seed stay in SpringTheme.of(context).colorScheme (in
a MaterialApp, also in Theme.of(context).colorScheme).
Import spring_gen/main.spring.dart to use them.
Names become Dart names: - and _ start a new word (surface-container-low
is surfaceContainerLow), a leading digit gets a $ in front (2xl is
$2xl) and a Dart keyword gets a $ behind (default is default$). Two
keys that give the same Dart name fail the build.
Pages of this reference
| Page | What it covers |
|---|---|
| Properties | Every property of spring.flutter.theme and of a theme: active, extends, brightness, which design starter reads which, and a theme downloaded from a URL |
| Colors | The 46 Material 3 color roles, the palette with and without a design starter, named colors, hex forms, alpha and mix |
| Typography | The 15 text roles and code, every style key, fonts from assets |
| Shape, spacing and elevation | The corner scale, spacing names and elevation levels |
| Tokens and references | Your own values, how a value is typed, $ references and $$ |
| Styles and states | A look per state for your own widgets, state precedence, ThemeStates, the colors of code |
| Motion and animations | Durations, curves, page transitions, animations.*, reduced motion |
| Background | A color, an image, an overlay and a slow animation behind every screen |
| Loaders and the splash | Spinners, dots, bars, skeletons, loaders of your own and the splash shown while the app starts |
| Images | Images from assets or the network, with a cache, a refresh, a checksum and a fallback |
The pages of a design are with its starter: Material's themes from properties, palette, density and ink and component themes; the Cupertino theme properties.
See also
- Design libraries: what a theme does without a design library, and with Material or Cupertino.
- spring_boot_starter_flutter_material and spring_boot_starter_flutter_cupertino.
- Configuration reference: config files, profiles, imports and placeholders, which all work inside a theme.
- Flutter testing: choosing a theme in a widget test and golden files.