
# Cupertino theme properties

The `cupertino` section of a theme sets what Cupertino's widgets read from their `CupertinoThemeData` and nothing in the rest of the theme covers. It is read by [spring_boot_starter_flutter_cupertino](index.md). It is a section of the theme itself, at `spring.flutter.theme.cupertino` (or `spring.flutter.theme.themes.<name>.cupertino` for one theme); it is not under `components`, which are Material's.

Without the section, the `CupertinoThemeData` is iOS's own look, with the theme's primary color where iOS uses its blue (see [Themes from properties](themes.md)).

## Why

- **iOS's look per theme, in YAML.** Bars, page backgrounds and the iOS text styles differ between a light, a dark and a branded theme; each theme writes them, or inherits them from the theme it extends.
- **Values that follow the palette.** A value may refer to a role (`$colors.primary`) or a token (`$brand.accent`). A dark theme that changes its colors changes every `cupertino` value that refers to them.
- **Checked at the start.** A misspelled key or a wrong value stops the start with the property's name and the valid keys.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    app:
      type: cupertino            # may be left out when this is the one design starter
    theme:
      seed-color: '#0057B8'
      typography:
        font-family: Inter
        title-large: { size: 17, weight: 600 }
      cupertino:
        primary-color: $colors.secondary
        primary-contrasting-color: white
        scaffold-background-color: '#F2F2F7'
        bar-background-color: { color: $colors.surface-container, alpha: 85% }
        selection-handle-color: $colors.primary
        apply-theme-to-all: true
        text-theme:
          nav-title-text-style: title-large
          nav-large-title-text-style: { size: 34, weight: 800, letter-spacing: 0.4 }
          action-text-style:
            color: $colors.primary
            weight: 500
```

```properties
# lib/resources/application.properties: the same
spring.flutter.app.type=cupertino
spring.flutter.theme.seed-color=#0057B8
spring.flutter.theme.typography.font-family=Inter
spring.flutter.theme.typography.title-large.size=17
spring.flutter.theme.typography.title-large.weight=600
spring.flutter.theme.cupertino.primary-color=$colors.secondary
spring.flutter.theme.cupertino.primary-contrasting-color=white
spring.flutter.theme.cupertino.scaffold-background-color=#F2F2F7
spring.flutter.theme.cupertino.bar-background-color.color=$colors.surface-container
spring.flutter.theme.cupertino.bar-background-color.alpha=85%
spring.flutter.theme.cupertino.selection-handle-color=$colors.primary
spring.flutter.theme.cupertino.apply-theme-to-all=true
spring.flutter.theme.cupertino.text-theme.nav-title-text-style=title-large
spring.flutter.theme.cupertino.text-theme.nav-large-title-text-style.size=34
spring.flutter.theme.cupertino.text-theme.nav-large-title-text-style.weight=800
spring.flutter.theme.cupertino.text-theme.nav-large-title-text-style.letter-spacing=0.4
spring.flutter.theme.cupertino.text-theme.action-text-style.color=$colors.primary
spring.flutter.theme.cupertino.text-theme.action-text-style.weight=500
```

`$colors.secondary` and `$colors.surface-container` are not declared here: a reference to an undeclared role reads the palette the theme's `seed-color` makes (see [The palette from a seed](palette.md)).

## The properties

Keys are written in kebab case here; `primaryColor` and `primary_color` are the same key. Every color is a [color value](#colors) of the theme.

| Property | Type | Default | What it changes |
|---|---|---|---|
| `cupertino.primary-color` | color | `colors.primary` when the theme declares it, else the primary of the palette of `seed-color` when it has one, else iOS blue (`systemBlue`) | The accent of Cupertino's widgets: the fill of a filled `CupertinoButton` and the text of a plain one, the active tab of a `CupertinoTabBar`, the cursor of a `CupertinoTextField`, sliders, segmented controls, the actions of the navigation bar. The action text styles carry it |
| `cupertino.primary-contrasting-color` | color | iOS's (white) | The color drawn on `primary-color`: the label and icon of a filled `CupertinoButton`, the unselected segments of a `CupertinoSegmentedControl` |
| `cupertino.scaffold-background-color` | color | `colors.surface` when the theme declares it; transparent when the theme has a [background](../spring-boot-starter-flutter/themes/background.md); else iOS's (`systemBackground`: white, or black in a dark theme) | The background of `CupertinoPageScaffold` and `CupertinoTabScaffold` |
| `cupertino.bar-background-color` | color | `components.app-bar.background-color` when the app also has `spring_boot_starter_flutter_material`, else iOS's translucent bar color (`#F0F9F9F9`, dark `#F01D1D1D`) | The background of `CupertinoNavigationBar`, `CupertinoSliverNavigationBar` and `CupertinoTabBar` |
| `cupertino.selection-handle-color` | color | iOS's (`systemBlue`), not the primary color | The handles of a text selection in Cupertino's text fields |
| `cupertino.apply-theme-to-all` | boolean | `false` | Whether the widgets that use iOS's fixed colors by default take the theme's instead. Today this is `CupertinoSwitch`: green when on, or `primary-color` with `true` |
| `cupertino.text-theme.primary-color` | color | `primary-color` | The color of the one action style no key here sets: the text of a small `CupertinoButton` (`sizeStyle: CupertinoButtonSize.small`). The action styles below already carry `primary-color`; give them a `color` to change theirs |
| `cupertino.text-theme.text-style` | text style | iOS's body style (17 points), with `typography.body-large` | The default style of text in Cupertino's widgets |
| `cupertino.text-theme.action-text-style` | text style | iOS's (17 points, in `primary-color`), with `typography.label-large` | The text of buttons and actions |
| `cupertino.text-theme.tab-label-text-style` | text style | iOS's (10 points, medium), with `typography.label-small` | The labels of a `CupertinoTabBar` |
| `cupertino.text-theme.nav-title-text-style` | text style | iOS's (17 points, semibold), with `typography.title-large` | The title in the middle of a navigation bar |
| `cupertino.text-theme.nav-large-title-text-style` | text style | iOS's (34 points, bold), with `typography.display-small` | The large title of a `CupertinoSliverNavigationBar` |
| `cupertino.text-theme.nav-action-text-style` | text style | iOS's (in `primary-color`), with `typography.label-large` | The buttons of a navigation bar (`leading`, `trailing`, the back button) |
| `cupertino.text-theme.picker-text-style` | text style | iOS's (21 points), with `typography.body-large` | The items of a `CupertinoPicker` and a `CupertinoTimerPicker` |
| `cupertino.text-theme.date-time-picker-text-style` | text style | iOS's (21 points), with `typography.body-large` | The items of a `CupertinoDatePicker` |

"With `typography.<style>`" means: when the theme sets a typography, the iOS style takes the theme's font and what `typography.<style>` writes (see [Themes from properties](themes.md#text-styles-from-the-typography)). A style written under `text-theme` replaces that.

The theme's `brightness` is the Cupertino theme's brightness: it is not a key of this section.

### Colors

Every color of the section is written the way colors are written everywhere in the theme (see [Writing a color](../spring-boot-starter-flutter/themes/colors.md#writing-a-color)):

| Form | Example | Notes |
|---|---|---|
| `#RRGGBB`, `#RGB` | `'#F2F2F7'` | Opaque. Quote it in YAML: `#` starts a comment |
| `#AARRGGBB` | `'#B3FFF1E6'` | Eight digits: **alpha first**, then red, green, blue. `B3` is 70% opaque. Not CSS's `#RRGGBBAA` |
| A `Colors` name | `white`, `transparent`, `teal.shade700` | Flutter's color names |
| A reference | `$colors.primary`, `$colors.on-primary`, `$brand.accent` | A role of the palette (declared, or made from the seed), or any value of the theme |
| A color object | `{ color: $colors.surface, alpha: 80% }` | A color with an opacity (`alpha`) or mixed with another (`mix: { with: white, amount: 20% }`) |

A role name alone is not a color: `bar-background-color: surface-container` fails the start; write `$colors.surface-container`.

A bar color that is not fully opaque makes the bar translucent: iOS blurs the page that scrolls under it, and `CupertinoPageScaffold` lets the content start under the bar. Three ways to the same kind of bar:

```yaml
spring:
  flutter:
    theme:
      cupertino:
        bar-background-color: '#CCF2F2F7'                           # #AARRGGBB: 80% opaque
      themes:
        ocean:
          cupertino:
            bar-background-color: { color: $colors.surface, alpha: 80% }   # follows the palette
        sunset:
          background: { color: $colors.surface }
          cupertino:
            scaffold-background-color: transparent                  # already the default with a background
            bar-background-color: '#B3FFF1E6'                       # 70% opaque, the picture shows through
```

### Text styles

Each style under `text-theme` is written in one of two ways:

```yaml
spring:
  flutter:
    theme:
      cupertino:
        text-theme:
          nav-title-text-style: title-large          # one of the theme's styles, by name
          action-text-style:                         # or a map
            style: label-large                       # the base (optional)
            color: $colors.primary
            font-family: Inter
            size: 17
            weight: semibold
            height: 1.3
            letter-spacing: -0.4
            italic: false
            decoration: none
```

| Key | Type | Values | What it does |
|---|---|---|---|
| a name | text | `display-large` ... `label-small` (the 15 styles), or `code` | The theme's style of that name, as `SpringTheme.of(context).textStyle(name)` gives it |
| `style` | text | the same names | The base the other keys change. Without it the base is iOS's own style for that slot |
| `color` | color | a [color](#colors) | Text color |
| `font-family` | text | a family | Font |
| `size` | number | logical pixels | Font size |
| `weight` | number or name | `100` ... `900`, `thin`, `light`, `normal`, `medium`, `semibold`, `bold`, `black` | Font weight |
| `height` | number | a multiple of the size | Line height |
| `letter-spacing` | number | logical pixels | Space between letters |
| `italic` | boolean | `true`, `false` | Italic or upright |
| `decoration` | enum | `none`, `underline`, `line-through`, `overline` | Text decoration |

What to know about each form:

- **A name** gives the theme's style: the theme's font, its on-surface color, and only the values `typography.<name>` writes. It does not add the Material 3 type scale's size; a style the typography gives no `size` has Flutter's default size. Name a style whose size your typography sets, as the example does with `title-large`.
- **A map without `style`** starts from iOS's style for the slot, not from the one made from the typography: `nav-title-text-style: { weight: 600 }` is iOS's navigation title in weight 600, in iOS's font. Add `font-family` (or a `style`) to keep the theme's font.
- **A map with `style`** starts from the theme's style of that name and changes it.
- A style you do not write keeps the one made from the typography, or iOS's.

## Values per theme

`cupertino` may be set in the root, for every theme, and changed in one theme. A theme that `extends` another starts from its `cupertino` values:

```yaml
spring:
  flutter:
    theme:
      cupertino:
        primary-color: $colors.primary
        bar-background-color: { color: $colors.surface, alpha: 80% }
      themes:
        graphite:
          extends: dark
          colors:
            primary: '#FF9F0A'
          cupertino:
            scaffold-background-color: transparent
            text-theme:
              nav-large-title-text-style: { size: 34, weight: 800, letter-spacing: 0.4 }
```

`graphite` keeps the root's `primary-color` (now orange, since it refers to `colors.primary`) and bar color, and adds its own scaffold and large title.

## Without the starter

In an app without `spring_boot_starter_flutter_cupertino`, a `cupertino` section is accepted, so that a theme library can carry values for Cupertino apps: it is not shown, not checked, and named once in the log. The key `cupertino` itself is still checked: `cupertio` fails the start. See [Properties of a design](../spring-boot-starter-flutter/themes/properties.md#properties-of-a-design).

## Differences from Material

- **Components.** `components.*` configure Material's `ThemeData`, read by `spring_boot_starter_flutter_material`. Cupertino's widgets read only `cupertino.*`, and `components.app-bar.background-color` (see [App bar](../spring-boot-starter-flutter-material/components/app-bar.md)) as the default bar color when the Material starter is in the app too.
- **States.** Material's component properties may have a value per state (`pressed`, `disabled`). Cupertino's theme has none: every `cupertino` value is one value.
- **Page transitions.** They are not in this section but in `motion.page-transition`, as in every app type. See [Page transitions](page-transitions.md).

## See also

- [Themes from properties](themes.md): how the `CupertinoThemeData` is made
- [The palette from a seed](palette.md)
- [Themes in code](themes-in-code.md): what no property covers
- [Colors](../spring-boot-starter-flutter/themes/colors.md)
- [Typography](../spring-boot-starter-flutter/themes/typography.md): the text styles Cupertino takes from
- [Tokens and references](../spring-boot-starter-flutter/themes/tokens-and-references.md)
- [Background](../spring-boot-starter-flutter/themes/background.md)
- [Theme properties of the Flutter starter](../spring-boot-starter-flutter/themes/properties.md)
