The page loader

The spring_flutter_page_loader builder writes a page loader into the app's web/index.html: what the browser shows from the first byte of the page until Flutter's own splash paints. It is made from the splash of the active theme, so the web page and the app's splash look the same. The same builder also fills the page's <head> and web/manifest.json from the configuration.

Why

A Flutter web app shows nothing until the browser has downloaded and started the engine and the app's code: often a few seconds of a white page. Flutter's splash only appears once Flutter runs, so it cannot cover that time.

The only thing a browser can show at once is the HTML of the page. So the builder turns the theme's splash into HTML and CSS at build time: the background, logo, title and loader of the splash, in the theme's colors. You describe the splash once, in the theme, and both the page and the app use it.

When it runs

The builder runs for a package that has a dependency (or dev dependency) whose name starts with spring_boot_starter_flutter, and whose web/index.html exists. A page that does not exist is not created. It never stops a build for a theme problem: what it cannot use is a warning. The theme's errors are reported by the typed keys builder.

It runs before spring_flutter_seo, so the pages for search engines are copies of a page that already has the loader.

Example

A theme with a splash that shows a logo, a title and a built-in bar loader:

# lib/resources/application.yml
spring:
  flutter:
    theme:
      loaders:
        boot:
          kind: bar
          color: '#336699'
          track: '#DDE6F0'
          height: 4
      splash:
        background: { color: '#FFFFFF' }
        logo: { source: assets/images/logo.png, size: 64 }
        title: Books
        loader: boot

The builder writes this block right after <body> (simplified: the fixed CSS rules and the script are shortened to ...):

<!-- spring:loader:start -->
<!-- Written by spring_core_dart_generator from the splash of the active theme; rewritten on every build. -->
<style id="spring-loader-style">
#spring-loader{position:fixed;top:0;right:0;bottom:0;left:0;z-index:2147483647;...;--spring-progress:0}
...
@media (prefers-reduced-motion:reduce){#spring-loader *{animation:none!important;transition:none!important}}
#spring-loader{background:#ffffff;color:#1a1a1a;--spring-logo-size:64px;--color:#336699;--track:#dde6f0;--height:4}
#spring-loader .sl-bar{width:calc(var(--width,220) * 1px);...}#spring-loader .sl-logo{width:var(--spring-logo-size);height:var(--spring-logo-size)}
</style>
<div id="spring-loader" role="status" aria-busy="true" aria-label="Loading" data-kind="bar" data-stage="start"><div class="sl-body"><img class="sl-logo" src="assets/assets/images/logo.png" alt="" decoding="async"><div class="sl-title">Books</div><div class="sl-kind"><div class="sl-bar"><span></span></div></div></div></div>
<script>
(function () {
  var root = document.getElementById('spring-loader');
  ...
})();
</script>
<!-- spring:loader:end -->

Step by step:

  1. The fixed rules lay the loader over the whole page (position:fixed, the highest z-index) and center its content.
  2. The #spring-loader{...} rule holds the page's background (background:#ffffff), a text color chosen from the background's brightness (#1a1a1a on a light background, #f5f5f5 on a dark one), the logo size, and every key of the loader as a CSS variable.
  3. The rules of the bar kind read those variables, with defaults: var(--height,3), var(--color, <the theme's primary>).
  4. The <div> holds the logo, the title and the loader's HTML.
  5. The script follows Flutter's start and removes the loader when Flutter is ready.

Where the block goes

The block lies between <!-- spring:loader:start --> and <!-- spring:loader:end -->.

The block is rewritten on every build, so edit the theme, not the block.

Which theme

The builder reads the theme as the typed keys builder does: every .properties, .yml and .yaml file of lib/resources/, whatever its profile, plus the files that spring.config.import names with resources: and that a dependency's lib/resources/ holds (a theme a library ships).

spring.flutter.theme.active picks the theme:

active The block The dark rule
A theme's name That theme's splash None
system, or not set The theme of system-light (light by default) The theme of system-dark (dark by default), inside @media (prefers-color-scheme:dark){...}

With system, the light theme must have a splash for any block to be written. The dark rule is added only when the dark theme has a splash too and its values differ; it repeats the #spring-loader{...} declarations with the dark theme's values. The loader's HTML is the light theme's, so both themes should use one loader kind.

Colors are resolved at build time: references ($colors.primary), color objects ({ color: $colors.primary, alpha: 14% }) and the Material roles that the seed color makes. This site's light theme declares primary: '#8A6A00', so its page gets theme-color #8a6a00.

What goes in

The background, logo and title

Splash key In the page
background.color The loader's background
background.gradient (type: linear or radial, colors, stops, begin, end) A linear-gradient(...) at the angle from begin to end, or a radial-gradient(circle min(80vw,80vh) at x% y%, ...) around begin. Needs at least two colors
neither The theme's surface color
logo.source <img class="sl-logo">. An asset path (assets/images/logo.png) becomes assets/assets/images/logo.png, the address Flutter serves assets at; an http(s):// URL and a data:image/ URL are used as they are. Anything else (another scheme, //, ..) gives no logo and a warning
logo.size --spring-logo-size, in pixels; 96 by default
title <div class="sl-title">, escaped for HTML
loader The name of a loader under loaders.*. A name that is no loader is a warning, and the page shows the logo and title only

Built-in loader kinds

The five built-in kinds (spinner, dots, pulse, bar, skeleton) have a CSS form. Each reads the loader's keys through their CSS variables, so a key such as color or size changes the page as it changes the app:

Kind HTML Variables it reads, with defaults
spinner a ring --color (primary), --size (40), --track (transparent), --animation-duration (900ms)
dots count dots (3 by default, 1 to 12) --color, --size (10), --animation-duration (900ms), --animation-curve (ease-in-out)
pulse a growing circle --color, --size (40), --animation-duration (1200ms), --animation-curve (ease-out)
bar a progress bar that follows --spring-progress --color, --track (primary at 20%), --width (220), --height (3), --radius (999)
skeleton three shimmering lines --base (surface-container-high), --highlight (surface-container-highest), --radius (6), --shimmer-angle (20), --shimmer-duration (1200ms)

Sizes are numbers of pixels: the CSS multiplies them (calc(var(--size,40) * 1px)).

A kind of the app's own: web:

A loader of a kind the app declares (@ThemeLoaderKind('spring-leaf')) is drawn by Dart code, which the page does not have. Its web: key names an HTML file that draws it in the page. The file's text goes into the block as it is. This site's loader:

# neon_farum_azula: lib/resources/application.yml (shortened)
loaders:
  spring-leaf:
    kind: spring-leaf
    phases:
      enter: { duration: 1400ms, curve: linear }
      fill: { progress: true, min-duration: 1.8s }
      exit: { duration: 700ms, curve: linear }
    leaf:
      color: $neon.green
      size: 120
    ring:
      track: { color: $neon.cyan, alpha: 14% }
    title:
      text: SPRING DART
    web: loaders/spring-leaf.html
splash:
  background: { color: '#04070D' }
  loader: spring-leaf
<!-- neon_farum_azula: lib/resources/loaders/spring-leaf.html (start) -->
<style>
#spring-loader .sk-leaf{width:calc(var(--leaf-size,120) * 1px);...}
#spring-loader .sk-title::before{content:var(--title-text)}
...
</style>
<div class="sk">...</div>

The file is looked for, in this order:

  1. lib/resources/<path> of the app;
  2. <path> below the app's directory;
  3. lib/resources/<path> of each package in the app's dependencies (a library that ships the theme and its loader).

A path must stay below the directory: an absolute path or one with .. is refused with a warning. A missing file is a warning, and the loader is left empty. A kind of the app's own without web: gets a built-in bar instead, with a warning.

A downloaded web: file

web: can also be an address, to share a loader without a package:

loaders:
  gate:
    kind: neon-gate
    web: github:owner/loaders/[email protected]
    web-sha256: 3f5a...e9   # the SHA-256 of the file, in hex
Address Downloaded from
https://... As written
github:owner/repo/path/to/file@ref raw.githubusercontent.com, at the branch, tag or commit ref
http://... Only with spring.remote.allow-insecure: true; otherwise an error

The download:

The HTML goes into your page as it is, scripts included. Take it from an address you trust, at a tag or commit, and pin it with web-sha256.

The loader's keys as CSS variables

Every key of the loader becomes a CSS variable on #spring-loader, named after its path in kebab case: leaf.size is --leaf-size, ring.track is --ring-track, title.letter-spacing is --title-letter-spacing. The top-level kind, web and web-sha256 are left out. The values:

Value In CSS Example from this site
A color, a reference to one, a color object #rrggbb, or rgba(r, g, b, a) with transparency --leaf-color:#2a8c52, --ring-track:rgba(11, 127, 143, 0.141)
A number Unitless: use calc(var(--x) * 1px) --leaf-size:120
A duration Milliseconds --phases-fill-min-duration:1800ms
true / false 1 / 0 --phases-fill-progress:1
A key named curve A CSS timing function: linear, ease, ease-in, ease-out, ease-in-out, and cubic-bezier(...) for decelerate, fast-out-slow-in, emphasized, emphasized-decelerate, emphasized-accelerate, ease-in-cubic, ease-out-cubic, ease-in-out-cubic; ease for any other --tracks-draw-curve:ease-out
Other text A quoted CSS string --title-text:"SPRING DART"
A list Its items joined with ,. A list of colors also gives its first color as --<name>-first, to close a circular gradient --edge-colors:#ff0000,#00ff00,#0000ff, --edge-colors-first:#ff0000

Insets and images are not written. Nothing in a theme can leave its place in the page: a CSS string escapes quotes, backslashes, <, >, & and line breaks, and the title and attributes are escaped for HTML. A title of </style><script>alert(1) stays text.

The page adds its own variables and attributes on #spring-loader:

Name Meaning
--spring-progress From 0 to 1: how far Flutter's start has come
data-stage start, then load, app, engine, run, done
data-splash-stage page when the page's script runs, engine when Flutter's engine starts
data-kind The loader's kind, in its plain form (springleaf for spring-leaf)
data-fill-at, data-fill-min For a loader whose progress phase has a min-duration: when that phase starts (after the animated phases before it) and its minimum, in milliseconds. This site has data-fill-at="1400" data-fill-min="1800". Not written when a looping phase comes first

The script

The script is the same in every app; only the attributes above change what it does.

  1. It follows Flutter's loader. It wraps _flutter.loader.load (also when flutter_bootstrap.js defines _flutter.loader later) and moves through the stages:

    Stage When Progress range
    load The page runs, and load is called 0.08 to 0.45
    app The app's entry point is loaded 0.5 to 0.6
    engine The engine starts 0.6 to 0.88
    run The engine is ready 0.9 to 0.95
    done Flutter's first frame (flutter-first-frame) 1

    Inside a stage, the progress creeps toward the stage's top. The shown value moves smoothly toward it, at most the whole range in 300 ms, and is written to --spring-progress on every animation frame. With data-fill-min, the shown progress is held to an eased clock, as the Flutter splash does.

  2. It reports the stages. window.springLoader exposes progress, stage, elapsed, stages (the stages reached, with their times) and handOff(). Each first stage also fires a spring-splash-stage event.

  3. It hands over to Flutter. When the Flutter splash has painted, spring_boot_starter_flutter calls window.springLoaderHandOff(progress). The script removes the loader's <div> and its <style>.

  4. It never stays forever. Without a hand-off, the loader is removed after 60 seconds, or 3 seconds after Flutter's first frame.

  5. It honours reduced motion. Under prefers-reduced-motion: reduce, a CSS rule stops every animation in the loader, and the progress no longer waits for the eased clock.

The Content Security Policy

The script's text never changes, so a Content Security Policy can allow it by its hash, 'sha256-...', which the generator exposes as WebPageLoader.scriptHash. The web dev server's ready policy of spa mode (spring.flutter.security.web.mode: spa) adds that hash to script-src when the active theme has a splash. It also adds the hashes of the scripts of swipe-to-close: false and max-pixel-ratio (below) when they are set (WebPageHead.hashOf). Each script is written with nothing else between its tags, so the hash the browser computes is the one in the policy. With your own policy, add the same hashes to its script-src.

The page's head and manifest

The same builder writes values of the configuration into the rest of web/index.html and into web/manifest.json, so they repeat nothing by hand. Flutter's template writes its own (A new Flutter project., the project's name, #0175C2): each value set in the configuration replaces the template's, and a value not set leaves the file's as it is. This happens on every build of a page, with or without a splash.

Source web/index.html web/manifest.json
spring.flutter.app.title <title>, and apple-mobile-web-app-title when the page has that tag name, short_name
spring.flutter.app.description <meta name="description">, added when missing description
The active theme's primary (#6750a4 when the theme gives none) <meta name="theme-color">, added when missing theme_color
The active theme's surface (#ffffff when the theme gives none) A background block (below) background_color

The colors are written whenever the app has spring.flutter.theme.* keys. With active: system (a light and a dark theme), the page gets both: two theme-color tags, the light theme's primary with media="(prefers-color-scheme: light)" and the dark theme's with media="(prefers-color-scheme: dark)", between <!-- spring:page:theme-color:start --> and <!-- spring:page:theme-color:end --> (they replace the page's own single tag), and a dark background in the background block, inside @media (prefers-color-scheme:dark){...}. A phone's browser bar then takes the color of the theme the visitor sees. The manifest has one color only, so it gets the light theme's. A page that carries the head of spring.flutter.web.seo.* keeps its own <title> and description: the SEO build wrote them for that page. The manifest is rewritten only when a value changes, not for its layout; a manifest that is no JSON object is left alone, with a warning.

More blocks go into the head, each between its own markers:

Block Markers When What
Viewport none: one <meta name="viewport"> The page has no viewport tag width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, the tag Flutter sets when it starts. Without it, a phone lays the page out about 980 points wide, so the loader shows at a third of its size and then jumps. A page's own tag is kept
Background <!-- spring:page:background:start --> / end The app has spring.flutter.theme.* keys <style>html,body{background-color:#f5f6f9}</style>: where Flutter does not draw (an app's browser resizing, a gap at an edge), the page is the theme's color, not white. With active: system, a @media (prefers-color-scheme:dark){...} rule adds the dark theme's surface
Theme color, light and dark <!-- spring:page:theme-color:start --> / end active: system, with a light and a dark theme Two <meta name="theme-color"> tags, the light primary for (prefers-color-scheme: light) and the dark one for (prefers-color-scheme: dark), in place of the single tag
Swipe to close <!-- spring:page:swipe:start --> / end spring.flutter.web.page.swipe-to-close: false A <style> and a <script> that keep an app's own browser (a messenger's, a social app's) from closing the page on a swipe down
Pixel ratio <!-- spring:page:pixel-ratio:start --> / end spring.flutter.web.page.max-pixel-ratio is a number of 1 or more A script, before the engine starts, that caps window.devicePixelRatio
Translation <!-- spring:page:translate:start --> / end, and translate="no" on <html> spring.flutter.web.page.translate is false <meta name="google" content="notranslate">: browsers and Google offer no translation, which could not work on text drawn on a canvas

This site's head, as written:

<meta name="theme-color" content="#8a6a00">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

<!-- spring:page:background:start -->
<style>html,body{background-color:#f5f6f9}</style>
<!-- spring:page:background:end -->
<!-- spring:page:swipe:start -->
<style>@media (pointer: coarse){html{scrollbar-width:none}...flutter-view{position:fixed!important;inset:0!important;...}}</style>
<script>(function(){if(!(window.matchMedia&&matchMedia('(pointer: coarse)').matches))return;...})();</script>
<!-- spring:page:swipe:end -->
<!-- spring:page:pixel-ratio:start -->
<script>(function(){var m=2;if(window.devicePixelRatio>m){try{window.devicePixelRatio=m;}catch(e){}}})();</script>
<!-- spring:page:pixel-ratio:end -->

Swipe to close

A link opened in a messenger or a social app shows in the app's own browser, which closes the page on a swipe down when the page is at its top. A Flutter page always is, as it scrolls inside its canvas, so every swipe down closes it. On a touch screen (pointer: coarse), the block makes the page a thousand screens tall, scrolls it to its end, fixes Flutter's view to the screen on all four sides, and stops the browser's own scrolling of the page (touchmove). The page is never at its top, so a swipe down is Flutter's. With the default, true, the block is removed.

Max pixel ratio

A phone's screen has 3 pixels for each point, so Flutter draws every frame at 9 times the pixels of the page, and a phone's graphics chip drops frames on a full-screen scroll. At 2, it draws 2.25 times fewer pixels, and text stays sharp. The browser scales the drawing to the screen. A screen at or under the value is left as it is. A value that is not a number of 1 or more is ignored, and the block removed.

Properties

The theme's keys come from every config file, whatever the profile (see "Which theme"). The other keys are read the way the app reads them in a browser: application.*, then application-web.* (which wins over it), the active profiles' files and the imports, as for the web dev server. When that reading fails, they count as not set.

Key Default Changes
spring.flutter.theme.active, system-light, system-dark system, light, dark Which theme's splash, and the dark rule
spring.flutter.theme.splash.* (or a theme's themes.<name>.splash.*) none The block: background, logo, title, loader
spring.flutter.theme.loaders.<name>.* (or a theme's) none The loader's kind, its CSS variables, its web: file and web-sha256
spring.flutter.theme.colors.*, the seed color (or a theme's) the seed's roles Resolved colors; primary and surface for the head and manifest
spring.flutter.app.title none <title>, apple-mobile-web-app-title, the manifest's names
spring.flutter.app.description none The description meta tag, the manifest's description
spring.flutter.web.page.swipe-to-close true false writes the swipe block
spring.flutter.web.page.max-pixel-ratio none Writes the pixel-ratio block
spring.flutter.web.page.translate true false writes the translation block
spring.remote.allow-insecure false true allows http:// addresses in web:

In Spring (Java)

Spring has no counterpart: a Spring application has no web page that waits for a client runtime to download.

See also