Theme properties
This page lists every property at the top of spring.flutter.theme and at
the top of a theme (themes.<name>). Properties that have their own page
(colors, typography, and so on) are listed here with a link.
spring:
flutter:
theme:
active: system
system-light: light
system-dark: dark
brightness: light
seed-color: deepPurple
scheme-variant: tonalSpot
contrast: 0
themes:
dark:
seed-color: deepPurple.shade200
ocean:
seed-color: teal
scheme-variant: vibrant
ocean-night:
extends: ocean
brightness: dark
The example is for an app with a design starter: seed-color,
scheme-variant and contrast make a palette that the Material or the
Cupertino starter calculates (see properties of a design).
Names are compared without case, - and _: seed-color, seedColor and
seed_color mean the same key. Any other key at this level stops the start
and the message lists the valid ones (a theme is themes.<name>.<property>
when you forgot the themes. part).
Which theme is shown
These keys exist at the root only. Inside themes.<name> they are an error.
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
active |
text | system or a theme name |
system |
The theme shown at start. ThemeSelection.select(...) changes it at run time. A name that is no theme stops the start and lists the themes |
system-light |
theme name | any theme | light |
The theme system shows when the device is in light mode |
system-dark |
theme name | any theme | dark |
The theme system shows when the device is in dark mode |
remember |
bool | true, false |
true |
Keeps the theme chosen with ThemeSelection.select between runs (in the app's files, spring/theme-choice; IndexedDB in a browser) and shows it again while the splash shows, so a reload does not flash the default theme. A ThemeChoiceStore bean keeps it elsewhere |
source, source-sha256, refresh |
none | A file downloaded for every theme, its values shared by all of them, under your own files. See a theme from a URL | ||
themes.<name> |
map | any theme name | none | A theme of your own, or the changes of light or dark. It holds the keys of the next two tables |
Where a theme comes from
These keys exist in themes.<name> only. They say where the theme starts
from, not how it looks.
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
extends |
theme name | light, dark or another theme |
the root | Start from that theme instead of the root. The theme gets everything the parent has, then its own keys on top. A cycle or an unknown parent stops the start |
source |
text | an https URL or github:owner/repo/path@ref |
none | Download the theme from this address. See a theme from a URL |
source-sha256 |
text | 64 hexadecimal digits | none | Refuse a download that does not have this digest |
refresh |
duration | 30m, 1h, 1.5d |
none | Look at the address again in the background when the cache is older than this |
What a theme sets
These keys exist at the root (shared by every theme) and in each
themes.<name>.
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
brightness |
enum | light, dark |
dark for the dark theme, light for others; inherited from the parent with extends |
Whether the theme is light or dark. It decides which tones the palette uses and what the system bars look like |
seed-color |
color | any color | Flutter's baseline Material 3 palette | The one color the whole palette is made from. Needs a design starter. See the palette from a seed |
scheme-variant |
enum | tonalSpot, fidelity, content, vibrant, expressive, monochrome, neutral, rainbow, fruitSalad (also tonal-spot and so on) |
tonalSpot |
How the palette is made from the seed. Needs a design starter. See scheme variants |
contrast |
number | -1 to 1 |
0 |
Palette contrast: -1 softer, 0 standard, 1 high. Needs a design starter. See contrast |
colors.<role> |
color | any color | from the seed, else Flutter's baseline | Sets one of the 46 palette roles by hand. See colors |
typography.* |
map | Material's | Font family, fallback fonts, the 15 text styles and code. See typography |
|
shape.<token> |
number | a radius, or infinity |
Material 3's | The corner scale. See shape, spacing and elevation |
elevation.<level> |
number | level0 to level5 |
0, 1, 3, 6, 8, 12 | The elevation levels. See shape, spacing and elevation |
spacing.<name> |
number | any name | xs 4, s 8, m 16, l 24, xl 32 |
The gaps of your own widgets. See shape, spacing and elevation |
visual-density, tap-target-size, splash (a word) |
enum | Flutter's | Material's density, tap targets and ink. Read by spring_boot_starter_flutter_material. See density and ink |
|
motion.page-transition |
enum, or a map of type, duration, curve |
platform, fade-upwards, zoom, cupertino, fade, none |
platform |
The page transition of every screen: the app type's own by default, as in Flutter; none switches pages at once. zoom needs spring_boot_starter_flutter_material, cupertino needs spring_boot_starter_flutter_cupertino; the others work in every app. See motion |
motion.durations.<name> |
duration | 250ms, 1.5s |
short 100ms, medium 250ms, long 450ms |
Named durations. See motion |
motion.curves.<name> |
curve | a curve name or four numbers | Material's standard easing | Named curves. See motion |
motion.text-change, motion.content-change, motion.scroll-to-top, motion.wheel-scroll, motion.overscroll |
enum or map | none, none, 400ms ease-out-cubic, none, platform |
How texts, contents, scrolls and overscrolls move. See motion | |
components.<component>.* |
map | Material 3's | Adjusts one of the 49 Material components. Read by spring_boot_starter_flutter_material. See component themes |
|
tokens.* |
any | none | Your own values, at any depth. See tokens and references | |
cupertino.* |
map | iOS's | The CupertinoThemeData. Read by spring_boot_starter_flutter_cupertino. See Cupertino theme properties |
|
styles.<name>.* |
map | none | A look per state for your own widgets. See styles and states | |
styles.code.* |
map | background, text, keyword, string, comment, number, key, annotation, variable, type, punctuation, inline-text, inline-background, header, title, padding, radius, border, border-width |
the color scheme | The colors of code in MarkdownView. See Markdown and code |
syntax.<language> |
map | rules (match, kind), keywords, types, aliases |
none | The languages of code blocks. See the languages of code |
animations.<name>.* |
map | none | Named animations: duration, curve, repeat. See motion |
|
background.* |
map | none | A color, image, overlay and animation behind every screen. See background | |
splash |
a map, or ripple, sparkle, none |
no splash screen | As a map, the splash screen shown while the app starts: background, logo, title, loader, animation, min-duration, exit. See loaders and the splash. As a word, Material's ink (see density and ink) |
|
loaders.<name>.* |
map | none | Loaders shown by ThemeLoader, ThemeSkeleton and the splash. See loaders |
|
frame-meter.* |
map | background, foreground, good, warning, bad, text-style |
from the color scheme and label-small |
The look of the frame meter |
Only these keys are accepted. Inside motion only page-transition,
text-change, content-change, scroll-to-top, wheel-scroll,
overscroll, durations and curves exist (see
motion).
Properties of a design
Some properties are read by a design starter, not by spring_boot_starter_flutter:
| Property | Read by | Documented in |
|---|---|---|
components.* |
spring_boot_starter_flutter_material |
Component themes |
visual-density |
spring_boot_starter_flutter_material |
Density and ink |
tap-target-size |
spring_boot_starter_flutter_material |
Density and ink |
splash as a word (ripple, sparkle, none) |
spring_boot_starter_flutter_material; a map under splash is the splash screen, read in every app |
Density and ink |
cupertino.* |
spring_boot_starter_flutter_cupertino |
Cupertino theme properties |
In an app without that starter they are accepted, as a theme library has
values for apps of each design. They are not shown and not checked, and one
INFO line on the logger spring_boot_starter_flutter.SpringThemes names 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.
Their keys are still checked: a misspelled componets stops the start.
SpringThemeData.unreadDesignProperties lists them, with the starter that
reads each.
seed-color, scheme-variant and contrast are different: they make a
Material 3 palette, which a design starter calculates (Material's or
Cupertino's, the same colors; see the palette from a seed).
Without one they stop the start; an app without a design library sets its
roles under colors.* (see colors).
Brightness
spring:
flutter:
theme:
themes:
night:
brightness: dark
seed-color: '#FF40A0'
A custom theme is light unless it says brightness: dark or extends a dark
theme. The palette is made for that brightness from the same seed (with a
design starter), or from Flutter's baseline and colors.* (without one).
Layers
A theme is the sum of layers, each over the one before:
brightness(darkfor thedarktheme, otherwiselight),- the root properties, or the resolved theme it
extends, - its own properties (without
extends,source,source-sha256andrefresh, which are about where it comes from).
A list in a later layer replaces the whole list of an earlier layer. In
styles, a later layer's plain value, list or map of states replaces one of
another shape; maps of states merge state by state.
A theme from a URL
A custom theme can be downloaded under a name your app chooses. The file's own name for its theme does not matter.
source on spring.flutter.theme itself (with its source-sha256 and
refresh) downloads values that every theme shares, under what your
own files set: the languages of code blocks
(syntax), a palette
of tokens. A themes.<name>.source is one theme, over its files.
spring:
flutter:
theme:
active: brand
themes:
brand:
source: https://themes.example.com/ocean.yml
source-sha256: 3f9a1c5e7b2d4a6f8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d1f3a
refresh: 1h
brand-dark:
extends: brand
brightness: dark
release:
source: github:neon/themes/ocean.yml@v3
| Property | What it does |
|---|---|
source |
An https URL, or github:owner/repo/path/to/theme.yml@ref, which means https://raw.githubusercontent.com/owner/repo/ref/path. ref is a branch, a tag or a commit; without it HEAD is used. http and any other scheme stop the start and name the property |
source-sha256 |
The file must have exactly this SHA-256 digest (lowercase hexadecimal, 64 digits). Another content is refused: not shown and not cached. It is part of the cache's identity |
refresh |
How old the cache may get before the file is read again in the background: 30m, 1h, 1.5d (a number with ms, s, m, h or d). Without it the first download is kept for ever |
source-sha256 and refresh need a source in the same theme.
How it works:
- The file is written like the theme part of
application.yml: underspring.flutter.theme, or with the theme keys at the top, or as onethemes.<any name>block. Only the look is taken, and it becomes your<name>.active,extends,system-light,system-dark,source,source-sha256,refreshand every otherspring.*setting in the file are ignored with a warning: a downloaded file never changes your other settings, picks the theme shown or points to more downloads. - The cache is in the app's
supportfiles place, inspring/themes/<sha256 of source and digest>/(theme.ymlandmeta.json). It survives restarts. Anothersourceorsource-sha256downloads again, and the cache folders of sources you no longer configure are removed at start. - Start. With a cache, the theme is applied at once, before the first
frame. With
refreshand an old cache the file is read again in the background (withIf-None-MatchandIf-Modified-Since; a304only renews the age) and the new theme is shown as soon as it arrives. Withoutrefreshthere is never another request. - No cache. The file is downloaded before the first frame, for at most 10 seconds and 1 MiB. Offline, a timeout, a wrong digest, a file that is too big, not UTF-8 or not a valid theme leave the theme your own files describe for that name; the next start tries again. A failed refresh keeps the theme in use and is tried again after the refresh time, but not later than five minutes.
- Redirects are followed only to
https. The request has no custom headers. - Typed keys. The generated
context.themecomes from the build. The downloaded file changes values; it does not add keys.
Kinds of addresses
An address is read by a chain of resolvers: the application's own first,
then github:owner/repo/path@ref and https:// / http://. Add a kind
(a company's cdn:) with a RemoteAddressResolver, given to
SpringApplication(addressResolvers: [...]), and every place that takes
an address (theme sources, images) accepts it. The build reads a page
loader's web: with the built-in kinds only.
Insecure connections
Every address the configuration downloads from (a theme's source, the
shared source, an image, a page loader's web:) is read the same way
(https://, github:owner/repo/path@ref) and checked at the start: an
http:// address stops the application with "the connection is not
secure", naming the address and its property. For a server without
https (a theme server of the local network, say):
spring:
remote:
allow-insecure: true
Then http:// works, as https:// with a certificate that is expired,
self-signed or for another host (not in a browser, which checks
certificates by itself), and a warning at the start lists every insecure
address. A page loader's web: is downloaded by the build, which applies
the same rule.
Related settings outside the theme
| Property | Type | Default | What it does |
|---|---|---|---|
spring.flutter.app.type |
widgets, material, cupertino |
not set: the one design starter's type (material, cupertino), else widgets; with several, required |
Which app widget is built. material (with spring_boot_starter_flutter_material) uses the Material ThemeData of the theme shown, cupertino (with spring_boot_starter_flutter_cupertino) the CupertinoThemeData |
spring.flutter.fonts.auto-load |
bool | true |
Load every .ttf and .otf file under flutter: assets: before the first frame. See typography |
spring.flutter.fonts.exclude |
list of globs | none | Font assets not to load |
Change a theme in code
Properties cover most themes. For the rest, each design starter has customizer beans that change every theme it makes, and beans that replace one: see themes in code of the Material starter and the Cupertino starter.