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. 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).

Why

Example

# 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
# 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).

The properties

Keys are written in kebab case here; primaryColor and primary_color are the same key. Every color is a color value 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; 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). 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):

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:

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:

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

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:

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.

Differences from Material

See also