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:

  1. brightness (dark for the dark theme, otherwise light),
  2. the root properties, or the resolved theme it extends,
  3. its own properties (without extends, source, source-sha256 and refresh, 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:

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.

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.

See also