
# 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](typed-keys.md) builder.

It runs before `spring_flutter_seo`, so the [pages for search engines](seo.md) 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:

```yaml
# 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 `...`):

```html
<!-- 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 -->`.

- 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:

```yaml
# 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
```

```html
<!-- 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:

```yaml
loaders:
  gate:
    kind: neon-gate
    web: github:owner/loaders/neon-gate.html@v1.2.0
    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 `https` only (`http` too 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.

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](web-dev-server.md)'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.*`](seo.md) 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:

```html
<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](web-dev-server.md). 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

- [Typed keys: context.theme and context.messages](typed-keys.md)
- [The web dev server](web-dev-server.md)
- [Pages for search engines](seo.md)
- [Properties the build reads](../build-properties.md)
