
# Density and ink

Three properties of a theme belong to Material alone: `visual-density`, how
tightly Material's controls are packed; `tap-target-size`, how large the area
is that a tap hits; and `splash` as one word, the ink that spreads where a
control is tapped. They set `ThemeData.visualDensity`,
`ThemeData.materialTapTargetSize` and `ThemeData.splashFactory` of every
theme they are written in.

## Why

Flutter picks all three per platform: compact and tight on desktops, roomy
and padded on phones, a sparkle on Android and a ripple elsewhere. An app
that wants the same look everywhere, or a dense layout for a tool on a
large screen, or no ink at all for a branded design, sets them once in the
theme instead of on every widget. Being theme properties, they can differ
per theme, per profile and per platform (`application-desktop.yml`).

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      visual-density: compact
      tap-target-size: shrink-wrap
      splash: ripple
      themes:
        touch:
          visual-density: standard
          tap-target-size: padded
          splash: sparkle
```

```properties
spring.flutter.theme.visual-density=compact
spring.flutter.theme.tap-target-size=shrink-wrap
spring.flutter.theme.splash=ripple
spring.flutter.theme.themes.touch.visual-density=standard
spring.flutter.theme.themes.touch.tap-target-size=padded
spring.flutter.theme.themes.touch.splash=sparkle
```

A dense desktop look only on desktops, with a profile of the platform:

```yaml
# lib/resources/application-desktop.yml
spring.flutter.theme:
  visual-density: compact
  tap-target-size: shrink-wrap
```

## The properties

| Key | Values | Default | In the `ThemeData` |
|---|---|---|---|
| `spring.flutter.theme.visual-density` | `adaptive`, `standard`, `comfortable`, `compact` | Flutter's: `standard` on Android, iOS and Fuchsia, `compact` on macOS, Windows and Linux | `visualDensity` |
| `spring.flutter.theme.tap-target-size` | `padded`, `shrink-wrap` (also `shrinkWrap`) | Flutter's: `padded` on Android, iOS and Fuchsia, `shrink-wrap` on macOS, Windows and Linux | `materialTapTargetSize` |
| `spring.flutter.theme.splash` | `ripple`, `sparkle`, `none` | Flutter's: `sparkle` on Android (not in a browser), `ripple` elsewhere | `splashFactory` |

Each also goes inside a named theme (`themes.<name>.visual-density`). Values
are compared without case, `-` and `_`. Another value fails the start and
names the property and the values it takes.

## Visual density

The density makes Material's controls smaller or larger than their
Material 3 size: buttons, chips, checkboxes, radios, list tiles, text fields,
icon buttons, menus. Each step takes about 4 logical pixels off the height
(and the width) of a control.

| Value | Steps (horizontal, vertical) | What it does |
|---|---|---|
| `standard` | `0, 0` | Material's own size |
| `comfortable` | `-1, -1` | A little tighter |
| `compact` | `-2, -2` | The tightest of the named values: lists and forms show more rows |
| `adaptive` | `standard` or `compact` | Flutter's choice for the platform the app runs on (`VisualDensity.adaptivePlatformDensity`): `compact` on desktops, `standard` elsewhere |

At the top of a theme only these four words are accepted. A component's own
`visual-density` also takes two numbers, `horizontal, vertical`, each from
`-4` to `4` (see [per component](#per-component)).

The density does not change text sizes or the padding of your own widgets;
for those, use the theme's [typography](../spring-boot-starter-flutter/themes/typography.md)
and [spacing](../spring-boot-starter-flutter/themes/shape-spacing-elevation.md#spacing).

## Tap target size

| Value | What it does |
|---|---|
| `padded` | Buttons, checkboxes, radios, switches, chips and icon buttons keep a tap area of at least 48 by 48 logical pixels, Material's minimum for touch, even when they look smaller. The extra area is transparent and answers taps |
| `shrink-wrap` | The tap area is as large as the control looks. Controls sit closer together; use it where a mouse is the pointer |

`padded` is about accessibility on touch screens: a 48 pixel target is
easier to hit with a finger. An app that runs on phones and desktops keeps
Flutter's per-platform default, or sets `shrink-wrap` in its desktop profile
only.

## Ink splash

The splash is the ink a Material control shows where it is tapped: on
`InkWell`, buttons, list tiles, chips, tabs.

| Value | Flutter's factory | What it does |
|---|---|---|
| `ripple` | `InkRipple.splashFactory` | A circle that grows from the tap and fades: the classic Material ripple |
| `sparkle` | `InkSparkle.splashFactory` | Material 3's ripple with a grain of sparkles. It is drawn by a shader |
| `none` | `NoSplash.splashFactory` | No ink. Hover, focus and pressed overlays still show |

`splash` has two meanings. A word is this ink, read by this starter. A map
is the splash screen shown while the app starts, read by every app (see
[the splash](../spring-boot-starter-flutter/themes/loaders.md#the-splash)).
One theme cannot have both under the same key: a theme with a splash screen
leaves the ink to Flutter's default, or sets it per component.

```yaml
spring:
  flutter:
    theme:
      splash:                   # a map: the splash screen of the start
        background: { color: $colors.surface }
        title: NEON Books
```

## Per component

The same three settings exist on single components, by Flutter's property
names, and win over the theme's for that component:

| Property | Components |
|---|---|
| `visual-density` (a word, or `horizontal, vertical`) | `button` and every button (`elevated-button`, `filled-button`, `outlined-button`, `text-button`, `icon-button`, `segmented-button`, `menu-button`), `checkbox`, `radio`, `list-tile`, `input`, `menu`, `menu-bar` |
| `tap-target-size` | `button` and every button |
| `material-tap-target-size` | `checkbox`, `radio`, `switch` |
| `splash-factory` (`ripple`, `sparkle`, `none`) | `button` and every button, `tab-bar` |

```yaml
spring:
  flutter:
    theme:
      visual-density: standard
      components:
        list-tile: { visual-density: '0, -2' }     # shorter rows only
        icon-button: { tap-target-size: shrink-wrap }
        tab-bar: { splash-factory: none }
```

The pages of [button](components/button.md), [checkbox](components/checkbox.md),
[list tile](components/list-tile.md) and [tab bar](components/tab-bar.md)
list them with the other properties.

## Read it in Dart

```dart
final theme = Theme.of(context);
theme.visualDensity;          // VisualDensity
theme.materialTapTargetSize;  // MaterialTapTargetSize
theme.splashFactory;          // InteractiveInkFeatureFactory
```

The theme as read, before Flutter's defaults, has them as `null` where they
are not set: `SpringTheme.of(context).visualDensity`, `.tapTargetSize` and
`.splashFactory` (extensions of this starter on `SpringThemeData`).

## Without this starter

In an app without `spring_boot_starter_flutter_material` (of type `widgets`
or `cupertino`), `visual-density`, `tap-target-size` and a single-value
`splash` are accepted, not shown and not checked: a theme library may carry
them for the apps that use Material. One INFO line of the log names each,
once. See [themes from properties](themes.md#without-this-starter).

## In Spring (Java)

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

## See also

- [Themes from properties](themes.md)
- [Component themes](components/index.md)
- [Theme properties](../spring-boot-starter-flutter/themes/properties.md)
- [Loaders and the splash](../spring-boot-starter-flutter/themes/loaders.md)
