
# Themes from properties

In an app with this starter, every theme of `spring.flutter.theme.*` is also
Material's `ThemeData`. The theme is written once, in the properties that
every app shares (colors, typography, shapes, motion, background: see
[Themes](../spring-boot-starter-flutter/themes/index.md)), plus a few that
only Material has. The starter makes the `ThemeData` of each theme, and
`MaterialApp`, `Theme.of(context)` and every Material widget use it. Only
what the properties set differs from Flutter's own Material 3 theme.

## Why

A Material app usually builds its `ThemeData` in Dart: a `ColorScheme`, a
`TextTheme`, a dozen component themes, once for light and once for dark.
Here the same theme is configuration. A designer changes `application.yml`,
a profile changes it per platform, a theme downloaded at run time changes it
without a release, and the same file serves a Material app, a Cupertino app
and an app without a design library.

## Example

From the Theme Showcase Material app of the framework's examples:

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      active: system
      seed-color: '#3F51B5'
      scheme-variant: tonalSpot
      typography:
        font-family: Inter
        title-large: { weight: 600 }
      shape:
        medium: 16
      components:
        app-bar:
          center-title: true
          background-color: $colors.primary-container
        card:
          elevation: 2
      themes:
        dark:
          brightness: dark
        ocean:
          extends: light
          seed-color: teal
          scheme-variant: vibrant
          shape: { medium: 20, large: 28 }
          colors:
            secondary: '#0277BD'
          components:
            card: { elevation: level0 }
        ocean-night:
          extends: ocean
          brightness: dark
```

```properties
spring.flutter.theme.active=system
spring.flutter.theme.seed-color=#3F51B5
spring.flutter.theme.scheme-variant=tonalSpot
spring.flutter.theme.typography.font-family=Inter
spring.flutter.theme.typography.title-large.weight=600
spring.flutter.theme.shape.medium=16
spring.flutter.theme.components.app-bar.center-title=true
spring.flutter.theme.components.app-bar.background-color=$colors.primary-container
spring.flutter.theme.components.card.elevation=2
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.ocean.extends=light
spring.flutter.theme.themes.ocean.seed-color=teal
spring.flutter.theme.themes.ocean.scheme-variant=vibrant
spring.flutter.theme.themes.ocean.colors.secondary=#0277BD
spring.flutter.theme.themes.ocean-night.extends=ocean
spring.flutter.theme.themes.ocean-night.brightness=dark
```

Widgets read the theme as in any Material app:

```dart
final scheme = Theme.of(context).colorScheme;
final title = Theme.of(context).textTheme.titleLarge;
Card(color: scheme.surfaceContainerLow, child: Text('Ocean', style: title));
```

## How a ThemeData is made

1. **The Flutter starter reads the theme** into a `SpringThemeData`: the
   layers of `light` or `dark`, the root, `extends` and the theme's own keys,
   with every `$` reference resolved. This is the same in every app.
2. **The palette is made** by this starter's design: from `seed-color`,
   `scheme-variant` and `contrast` with Material's `ColorScheme.fromSeed`,
   or Flutter's baseline when none is set, then the roles of `colors.*`
   over it (see [The palette from a seed](palette.md)).
3. **The `ThemeData` is made** of the theme (`toMaterial()`), then each
   component under `components.*` is applied to it.
4. **The `ThemeCustomizer` beans change it**, in `@Order`; a `ThemeData` bean
   named `theme` or `darkTheme` takes the place of the made `light` or `dark`
   theme before them (see [Themes in code](themes-in-code.md)).
5. **The `MaterialThemes` bean keeps the result**, made once per theme, and
   the `MaterialApp` shows it.

### What comes from the Flutter starter

These parts are the Flutter starter's properties, the same in every app. This
starter puts them where Material's theme has a place for them:

| Theme property | In the `ThemeData` |
|---|---|
| The 46 palette roles: `colors.*`, or made from the seed | `colorScheme`, Material's `ColorScheme` with every role of the theme's palette |
| `typography.font-family`, `typography.font-family-fallback` | `fontFamily`, `fontFamilyFallback` |
| The 15 text styles (`display-large` ... `label-small`) | `textTheme`: a style the theme sets replaces Material's, the others stay Material's |
| `shape.*` | No field of its own: the components that follow a token (cards `medium`, dialogs `extra-large`, buttons `full`, ...) take it when the theme changes that token, and a component's `shape: large` reads it (see [components](components/index.md#shapes-and-elevations)) |
| `elevation.*` | A component's `elevation: level2` reads the level |
| `motion.page-transition` | `pageTransitionsTheme`, the same transition on every platform; with `platform` (or nothing set) Flutter's own per platform |
| `background` | `scaffoldBackgroundColor` is transparent, so the background shows through every `Scaffold` |
| What Material has no place for: `spacing`, `tokens`, `styles`, the `code` style, `animations`, `loaders` | The `SpringThemeExtension` among `extensions` (see [below](#reading-the-theme)) |

### What this starter adds

| Theme property | In the `ThemeData` | Page |
|---|---|---|
| `seed-color`, `scheme-variant`, `contrast` | The palette Material 3 makes of them | [The palette from a seed](palette.md) |
| `components.<name>.*` | About fifty component themes: `cardTheme`, `appBarTheme`, `filledButtonTheme`, `inputDecorationTheme`, ... | [Component themes](components/index.md) |
| `visual-density` | `visualDensity` | [Density and ink](density-and-ink.md) |
| `tap-target-size` | `materialTapTargetSize` | [Density and ink](density-and-ink.md) |
| `splash` (one word) | `splashFactory` | [Density and ink](density-and-ink.md) |
| `motion.page-transition: zoom` | `ZoomPageTransitionsBuilder`, Material's zoom transition | [Motion](../spring-boot-starter-flutter/themes/motion-and-animations.md#page-transitions) |

All of them also go inside a named theme (`themes.<name>.components.card.*`).
`seed-color`, `scheme-variant` and `contrast` are calculated by the
[Cupertino starter](../spring-boot-starter-flutter-cupertino/palette.md) too,
with the same colors; the others are Material's alone.

## Light, dark and system

`light` and `dark` always exist; `spring.flutter.theme.active` picks what is
shown:

| `active` | The `MaterialApp` gets |
|---|---|
| `system` (the default) | `theme`: the theme of `system-light` (default `light`), `darkTheme`: the theme of `system-dark` (default `dark`), `themeMode: ThemeMode.system`. Material switches between them with the device |
| A theme's name | `theme`: that theme, `themeMode: ThemeMode.light`. A dark theme is shown as it is, since its palette is dark |

The `ThemeSelection` bean changes the choice at run time, and the app shows
the new theme at once:

```dart
class ThemeMenu extends SpringStatelessWidget<(ThemeSelection,)> {
  const ThemeMenu({super.key});

  @override
  Widget build(BuildContext context) {
    final (selection,) = beans;
    return PopupMenuButton<String>(
      onSelected: selection.select,
      itemBuilder: (_) => [
        for (final name in ['system', 'light', 'dark', 'ocean'])
          PopupMenuItem(value: name, child: Text(name)),
      ],
    );
  }
}
```

See [Themes](../spring-boot-starter-flutter/themes/index.md#how-a-theme-is-chosen)
for `system-light`, `system-dark`, `remember` and `extends`.

## Themes loaded at run time

A theme can arrive after the start: from a URL in the properties
(`themes.<name>.source`, see
[a theme from a URL](../spring-boot-starter-flutter/themes/properties.md#a-theme-from-a-url)),
or from code with the `SpringThemes` bean:

```dart
@Service()
class WinterThemes {
  WinterThemes(this.themes, this.selection);

  final SpringThemes themes;
  final ThemeSelection selection;

  Future<void> show() async {
    themes.loadYaml(
      await http.read(Uri.parse('https://themes.example.com/winter.yml')),
    );
    selection.select('winter');
  }
}
```

A loaded theme is checked as the themes of the files are, Material's part
too: an unknown component or a wrong value throws a
`ThemePropertyException` and changes nothing. Then the `MaterialThemes` bean
makes its `ThemeData` (with the customizers) when it is first shown.

## The properties this starter reads

| Key | Values | Default | What it does |
|---|---|---|---|
| `spring.flutter.theme.seed-color` | a color | none | The color the palette is made from |
| `spring.flutter.theme.scheme-variant` | `tonalSpot`, `fidelity`, `content`, `vibrant`, `expressive`, `monochrome`, `neutral`, `rainbow`, `fruitSalad` | `tonalSpot` | How the palette is made from the seed |
| `spring.flutter.theme.contrast` | `-1` to `1` | `0` | The contrast of the palette |
| `spring.flutter.theme.components.<name>.*` | see the [component reference](components/index.md) | Flutter's | The theme of one Material component, by Flutter's property names in kebab case |
| `spring.flutter.theme.visual-density` | `adaptive`, `standard`, `comfortable`, `compact` | Flutter's per platform | How densely Material's controls are packed |
| `spring.flutter.theme.tap-target-size` | `padded`, `shrink-wrap` | Flutter's per platform | The minimum area a tap hits |
| `spring.flutter.theme.splash` | `ripple`, `sparkle`, `none` | Flutter's per platform | The ink of a tap. A map under `splash` is something else: the splash screen of the start, which every app reads |
| `spring.flutter.theme.motion.page-transition` | `zoom` | | Material's zoom transition; the other values are the Flutter starter's |

## Checked at the start

The starter reads its part of every theme when the application starts, not
when a widget first needs it: an unknown component or property, a wrong
value, or a combination Flutter refuses fails the start and names the
property and the valid values, with a "did you mean" where one is close (the list is shortened here):

```text
Invalid theme property spring.flutter.theme.components.crad (theme light): ''; expected a component: app-bar, badge, banner, ... (did you mean 'card'?).
```

A theme loaded at run time is checked the same way, before it replaces
anything.

## Without this starter

A theme may carry `components`, `visual-density`, `tap-target-size` and a
single-value `splash` in an app without this starter: a theme library has
them for the apps that use Material. There they are accepted, not shown and
not checked, and one INFO line of the log tells each, once:

```text
The theme property components is not shown and not checked: spring_boot_starter_flutter_material, which reads it, is not in the application.
```

The key is still checked: `componets` fails the start.
`SpringThemeData.unreadDesignProperties` lists them, with the starter that
reads each. `seed-color`, `scheme-variant`, `contrast` and the `zoom`
transition are different: without a design starter they fail the start,
naming it. In an app with both design starters, Material's properties are
read and checked whatever the app's type. See
[Design libraries](../spring-boot-starter-flutter/design-libraries.md).

## Reading the theme

Material's widgets read `Theme.of(context)`. What Material's theme has no
place for is in the `SpringTheme`, in every app:

```dart
final theme = SpringTheme.of(context);
final gap = theme.space('m');
final code = theme.textStyle('code');
```

Code that has only Material's `ThemeData` at hand (a `ThemeData` passed to a
function, a widget below a `Theme` of its own) reaches it through the
extension every made `ThemeData` carries:

```dart
final spring = Theme.of(context).extension<SpringThemeExtension>()!.data;
final gap = spring.space('s');
```

A theme other than the one shown, as Material's `ThemeData`, comes from the
`MaterialThemes` bean, customized like the app's:

```dart
// In a widget: the bean, injected.
class OceanPreview extends SpringStatelessWidget<(MaterialThemes,)> {
  const OceanPreview({super.key});

  @override
  Widget build(BuildContext context) {
    final (themes,) = beans;
    return Theme(data: themes.theme('ocean'), child: const PreviewCard());
  }
}

// Outside a widget: from the application context.
final ocean = MaterialThemes.of(applicationContext).theme('ocean');
```

`SpringThemeData.toMaterial()` gives the `ThemeData` of one theme without
the customizers, and `materialColorScheme` its palette as Material's
`ColorScheme`.

## In Spring (Java)

There is no counterpart: Spring has no themes for apps.

## See also

- [Themes](../spring-boot-starter-flutter/themes/index.md): the properties every app shares
- [The palette from a seed](palette.md)
- [Density and ink](density-and-ink.md)
- [Component themes](components/index.md)
- [Themes in code](themes-in-code.md)
- [Design libraries](../spring-boot-starter-flutter/design-libraries.md)
