Theme images

A theme can name images: the background image, the images of single screens, and image tokens you read in Dart. All use the same map. An image is either an asset of the app or a file from the network. Network images are downloaded in the background, kept in a cache that survives restarts, checked against a SHA-256 digest if you give one, and refreshed when you ask.

spring:
  flutter:
    theme:
      background:
        image:
          source: https://cdn.example.com/neon/background.jpg
          refresh: 1d
          source-sha256: 9f2c1a5e7b2d4a6f8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d1f3a
          headers:
            Authorization: Bearer ${cdn.token}
          timeout: 10s
          fallback: assets/images/background.jpg
      tokens:
        brand:
          hero:
            source: https://cdn.example.com/hero.png
            refresh: 1d

Properties

Property Type Values Default What it does
source text an asset path, an https:// URL, a github:owner/repo/path@ref address required Where the image is. A path with no scheme (and a Windows drive such as C:) is an asset; an address is downloaded. http:// stops the start unless spring.remote.allow-insecure is true (see insecure connections). Any other scheme stops the start
refresh duration 30m, 12h, 1.5d none How old the cache may get before the file is looked at again in the background. Without it the first download is kept for ever and there is never another request
source-sha256 text 64 hexadecimal digits none The file must have exactly this digest. Any other file is refused
headers map header name to value none Request headers, such as Authorization. ${...} placeholders are resolved by the application's configuration. Header names keep their spelling
timeout duration 10s, 1m 10s The longest a download may take
fallback text an asset path none An asset shown while a network image is not there yet

Durations here are the same as everywhere in a theme: a number (decimals allowed) with a unit (ms, s, m, h, d), like 1.5s or 0.5d. A plain number is milliseconds. ISO-8601 (PT1H30M) is not accepted.

In a background image these keys sit next to fit, alignment, opacity and blur. Any other key stops the start and lists the valid ones.

References ($colors.primary) are not resolved in source, fallback, source-sha256 or headers, so a $ in a secret that came from a placeholder stays exactly as it is. See tokens and references.

What is shown, and when

The start never waits for the network.

Situation What the app shows
An asset The asset, at once
A network image with a cache The cached image, at once
A network image without a cache, with a fallback The fallback; the download runs in the background and the image replaces it when it arrives
A network image without a cache and without a fallback Nothing; for a background, its color

When a download ends, the new image fades in (for a background, over its transition).

Downloads and the cache

Image tokens

A token that is a map with a source and only the keys of the table above is an image. A map with another key next to source is a group of tokens. The image sits at least at tokens.<group>.<key>.

spring:
  flutter:
    theme:
      tokens:
        neon:
          hero: { source: https://cdn.example.com/hero.png, refresh: 1d }
          logo: { source: assets/images/logo.png }
final hero = context.theme.tokens.neon.hero;      // a ThemeImage
ValueListenableBuilder(
  valueListenable: hero.listenable,
  builder: (context, provider, _) =>
      provider == null ? const SizedBox() : Image(image: provider),
);

ThemeImage.provider is the image to paint now (null while a network image has neither a cache nor a fallback), and listenable notifies when a download arrives or is refreshed. theme.tokenImage('neon.hero') reads the same image without the generator.

Errors

A wrong value stops the start and names the property, for example tokens.neon.hero.source-sha256 with "must be 64 hexadecimal digits". An http:// source stops the start with "the connection is not secure", naming the address and its property, unless spring.remote.allow-insecure is true. A missing source is an error too: every image needs one.

See also