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
- 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 everycupertinovalue 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
# 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:
- 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 nosizehas Flutter's default size. Name a style whose size your typography sets, as the example does withtitle-large. - A map without
stylestarts 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. Addfont-family(or astyle) to keep the theme's font. - A map with
stylestarts 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:
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
- Components.
components.*configure Material'sThemeData, read byspring_boot_starter_flutter_material. Cupertino's widgets read onlycupertino.*, andcomponents.app-bar.background-color(see App bar) 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: everycupertinovalue is one value. - Page transitions. They are not in this section but in
motion.page-transition, as in every app type. See Page transitions.
See also
- Themes from properties: how the
CupertinoThemeDatais made - The palette from a seed
- Themes in code: what no property covers
- Colors
- Typography: the text styles Cupertino takes from
- Tokens and references
- Background
- Theme properties of the Flutter starter