Theme background

A theme can have a background: a base color, an image, something painted over the image (a color or a gradient), and a slow movement of the image. The app paints it behind every screen. A theme switch or a new image cross-fades. One screen (a login screen, say) can have its own background.

spring:
  flutter:
    theme:
      animations:
        background-drift:
          duration: 40s
          curve: ease-in-out
          repeat: reverse
      background:
        color: $colors.surface-container-lowest
        image:
          source: https://cdn.example.com/neon/background.jpg
          fallback: assets/images/background.jpg
          refresh: 1d
          fit: cover
          alignment: center
          opacity: 0.9
          blur: 4
        overlay:
          color: '#330A0C12'
          gradient:
            type: linear
            begin: top
            end: bottom
            colors: [transparent, '#CC0A0C12']
            stops: [0, 1]
        animation: background-drift
        effect: drift
        transition: 400ms ease-out
        screens:
          login:
            image:
              source: assets/images/login.jpg
              blur: 0
            overlay:
              color: '#66000000'

Properties

A theme has no background unless it has at least one key under background. Any other key stops the start and lists the valid ones.

The background

Property Type Values Default What it does
background.color color any color the theme's surface The base layer under everything else. It also shows while the image loads
background.image map the image keys below none A picture painted over the color
background.overlay map color, gradient none What is painted over the image
background.animation text the name of an animations.<name> none The animation that moves the image
background.effect enum drift, zoom, pulse drift when animation is set How the image moves
background.transition text <duration> [<curve>], such as 400ms ease-out 300ms ease-out The cross-fade when the background changes
background.frame-rate number or every-frame over zero 15 How many times a second the moving image is drawn again
background.screens.<name> map the keys above except screens none A background for one screen. See per-screen backgrounds

The image

background.image takes every key of an image (source, refresh, source-sha256, headers, timeout, fallback, allow-http) and four keys about how the picture fills the screen.

Property Type Values Default What it does
source text an asset path, an https URL, an http URL with allow-http required The picture. See images for the download, cache and refresh keys
fit enum cover, contain, fill, fit-width, fit-height, none, scale-down cover How the picture fills the screen
alignment alignment see below center Which part of the picture stays in view
opacity number 0 to 1 1 How opaque the picture is. The color shows through the rest
blur number 0 or more 0 How much the picture is blurred (a Gaussian blur of that radius in logical pixels). 0 is sharp

Values of fit:

Value What it does
cover Fills the screen and keeps the shape, cropping what does not fit
contain Shows the whole picture inside the screen, keeping its shape, and leaves empty space
fill Stretches the picture to the screen, changing its shape
fit-width Makes the width match the screen; the height may be cropped or short
fit-height Makes the height match the screen; the width may be cropped or short
none Shows the picture at its own size
scale-down Like contain, but never makes the picture bigger than its own size

Values of alignment:

Value Position
center Centre
top or top-center Top edge, centre
bottom or bottom-center Bottom edge, centre
left or center-left Left edge, centre
right or center-right Right edge, centre
top-left, top-right, bottom-left, bottom-right The corners
x, y Two numbers from -1 (left or top) to 1 (right or bottom); 0, 0 is the centre, 0, -0.5 is half way to the top

fit and alignment matter when the picture and the screen have different shapes. With cover, alignment: top keeps the top of the picture.

The overlay

An overlay is painted over the image, so text stays readable. It can have a flat color, a gradient, or both (the gradient is on top).

Property Type Values Default What it does
overlay.color color any color, with alpha none A flat color over the whole screen. Use a color with some transparency ('#330A0C12', { color: $colors.scrim, alpha: 30% })
overlay.gradient.type enum linear, radial linear The kind of gradient
overlay.gradient.begin alignment same as alignment top (linear), center (radial) Where a linear gradient starts. For a radial gradient it is the centre
overlay.gradient.end alignment same as alignment bottom Where a linear gradient ends. A radial gradient does not use it: giving end with type: radial stops the start ("radial uses begin as its center")
overlay.gradient.colors list of colors at least two required The colors, from begin to end (or from the centre outwards)
overlay.gradient.stops list of numbers 0 to 1, as many as colors even spacing Where each color sits along the gradient

A radial gradient has a radius of 0.8 of the screen's shorter side. colors and stops are YAML lists or one comma-separated value. A list of fewer than two colors, or stops with a different length than colors, stops the start.

spring:
  flutter:
    theme:
      background:
        color: '#0A0C12'
        overlay:
          gradient:
            type: radial
            begin: top-right
            colors: ['#33FF40A0', transparent]

The painting order

From the back to the front: color, the image (blurred, with its opacity), overlay.color, overlay.gradient. Only the image moves when there is an animation; the color and the overlay stay still.

Animation and effect

animation names an entry of animations of the same theme; a name that is not one stops the start and lists the animations (an animation of this theme must exist). It gives the speed, the curve and the repeat. effect says what the image does with the progress t that goes from 0 to 1:

Effect What the image does
drift The image is made 12% larger, so no edge shows, and slides slowly to and fro: up to 4% of the width across and 2% of the height up and down
zoom The image grows from its normal size to 12% larger
pulse The image fades a little in and out: between 70% and 100% of its opacity

Notes:

The frame rate

A moving background is the whole screen: each time it moves, everything on the screen is drawn again. A drift of 40 seconds moves the image a pixel or two a second, so drawing it at every frame (60 or 120 a second) keeps the screen repainting while nothing else changes. On the web this takes the time scrolling needs and the battery.

frame-rate is how many times a second the image moves on: 15 by default, which a slow drift cannot tell from every frame. Between two of its steps the screen is not drawn for the background. every-frame moves it at every frame of the screen, for a fast animation:

background:
  animation: background-drift
  effect: drift
  frame-rate: 10          # or every-frame

The transition

transition is the cross-fade when the background changes: a theme switch, a new image from the network, or a changed color. It is a duration and an optional curve: 400ms ease-out, 1s, 250ms linear. The default is 300ms ease-out. When the device asks for less motion, there is no fade.

A new network image is loaded first and fades in over the old one, so there is never an empty flash.

Per-screen backgrounds

background.screens.<name> changes the background for the screen with that name. It uses the same keys, except screens.

spring:
  flutter:
    theme:
      background:
        color: $colors.surface
        image: { source: assets/images/main.jpg, opacity: 0.8 }
        screens:
          login:
            image: { source: assets/images/login.jpg }
          settings:
            image: { blur: 12 }         # same picture as the theme's, blurred
            overlay: { color: '#80000000' }

A screen starts from the theme's background and changes what it writes:

Names are compared without case, - and _.

Show it

SpringApp (that is, SpringApplicationWidget) puts the background around the app's navigator when the active theme has one, so every screen shows it. To make that visible it also makes the Material scaffold (in a MaterialApp, with spring_boot_starter_flutter_material) and the Cupertino page (in a CupertinoApp, with spring_boot_starter_flutter_cupertino) background transparent for a theme with a background. A Cupertino theme that sets cupertino.scaffold-background-color keeps its color.

Three widgets give a screen control:

// The theme's background (this is what the app itself uses).
ThemeBackground(child: const HomePage());

// background.screens.login over the theme's own. A name the theme does not
// list throws a FlutterError in debug (it lists the screens the theme has,
// and the closest name); in release it shows just the child.
ThemeBackground.screen('login', child: const LoginForm());

// A plain surface-colored background that hides the theme's one.
ThemeBackground.none(child: const ReaderPage());

Read the values in Dart with context.theme.background. It is a ThemeBackgroundData?, null in a theme without a background:

final bg = context.theme.background;
bg?.color;          // Color?
bg?.screen('login'); // the login screen's resolved background

A theme without a background has opaque scaffolds again. If a theme switch adds or removes the background, the screens keep their state.

See also