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:
- The fixed rules lay the loader over the whole page (
position:fixed, the highestz-index) and center its content. - The
#spring-loader{...}rule holds the page's background (background:#ffffff), a text color chosen from the background's brightness (#1a1a1aon a light background,#f5f5f5on a dark one), the logo size, and every key of the loader as a CSS variable. - The rules of the
barkind read those variables, with defaults:var(--height,3),var(--color, <the theme's primary>). - The
<div>holds the logo, the title and the loader's HTML. - 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 -->.
- When the markers are there, the block between them is replaced. Nothing else of the file changes.
- When they are missing, the block is put right after
<body>(or before</html>, or at the end, for a page without<body>). - When the active theme has no splash, the block is removed, markers included.
- When the markers are not one pair in the right order (a start without an end, two starts), the builder warns and changes nothing in the file, the head included. Fix or remove the markers.
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:
lib/resources/<path>of the app;<path>below the app's directory;lib/resources/<path>of each package in the app'sdependencies(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:
- takes at most 10 seconds, and follows at most 5 redirects, to
httpsonly (httptoo when insecure connections are allowed); - refuses a file larger than 512 KiB;
- with
web-sha256, refuses a file of another digest and does not keep it; - keeps a copy in
.dart_tool/spring/loaders/, keyed by the address and the pin. When a later download fails, the copy is used, with a warning, so a build offline still works.
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.
-
It follows Flutter's loader. It wraps
_flutter.loader.load(also whenflutter_bootstrap.jsdefines_flutter.loaderlater) and moves through the stages:Stage When Progress range loadThe page runs, and loadis called0.08 to 0.45 appThe app's entry point is loaded 0.5 to 0.6 engineThe engine starts 0.6 to 0.88 runThe engine is ready 0.9 to 0.95 doneFlutter'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-progresson every animation frame. Withdata-fill-min, the shown progress is held to an eased clock, as the Flutter splash does. -
It reports the stages.
window.springLoaderexposesprogress,stage,elapsed,stages(the stages reached, with their times) andhandOff(). Each first stage also fires aspring-splash-stageevent. -
It hands over to Flutter. When the Flutter splash has painted,
spring_boot_starter_fluttercallswindow.springLoaderHandOff(progress). The script removes the loader's<div>and its<style>. -
It never stays forever. Without a hand-off, the loader is removed after 60 seconds, or 3 seconds after Flutter's first frame.
-
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.