Skip to the content

Spacing & Dimensions

Spacing is a named scale on a 4px grid. The dimension prop sets its density — compact, normal or spacious — for the whole theme, so the same screen can be tight in a dashboard and airy on a landing page without touching a component.
Theming

The scale

Every spacing prop (p, m*, gap, …) takes an alias. Values below are for dimension="normal".

Alias
Use
rem
px
zero
no space
0
0
micro
inner spacing of groupings
0.25
4
xs
line spacing within groupings
0.5
8
small
inputs and inner blocks
0.75
12
medium
between components (the default step)
1
16
large
between component blocks
1.75
28
xl
between content blocks
2.75
44
xxl
between page sections
4.5
72
giant
between distinct pieces of content
7.25
116
Scrolls sideways inside the table. The page does not.
loading

Density

dimension changes the multiplier per scale unit: compact 0.20rem (about 20% denser), normal 0.25rem, spacious 0.32rem (about 28% airier). It scales every spacing alias — gaps, paddings, the inner space of inputs, and any theme.spacing(...) call. It does not change text size, icons, colors, borders, radius or shadows.

compact
normal
spacious
import { ApollionProvider } from '@apollion-dsi/core/themes';

<ApollionProvider dimension="compact" textSize="larger">
  <Dashboard />
</ApollionProvider>;

dimension is a provider prop (also accepted by createTheme), with no hook and no theme.dimension getter: components read the resolved values, never the axis name. The root font size is fixed, not fluid, so wide screens gain columns, not inflated components.

Pitfalls

  • A nested provider for a dense region inside an airy page → it works, but it rebuilds the whole theme; pass colors again and syncDocument={false}.
  • Expecting compact to shrink text → pair it with textSize.
  • Reading theme.spacing(12) as 12px → a number counts scale units (12 is 3rem at normal); use an alias such as theme.spacing('small').

See also