field-ui

API reference

data-* attributes

A body is configured entirely in markup. Each force reads only the attributes it uses and ignores the rest, so you can set a few and compose freely.

All attributes

data-body tokens
Space-separated force ids — required to make an element a body. Forces compose.
data-strength number · default 0.5
Force magnitude S.
data-range px · default 280
Influence radius d_max.
data-spin number · default 1
Sign/strength of rotation — swirl, charge, magnetism, lens.
data-angle deg · default 0
Heading — stream, jet, gate, shear, align.
data-color hex
Accent override on engage, and the carried colour for pigment.
data-when condition · default ''
Gate the force on a condition: active, fast, slow, hot, cool, scrolling.
data-feedback flag
Opt into two-way density write-back (the --d custom property).
data-shaped flag
Shaped source — forces reference the nearest point on the element box, so matter shells the shape instead of bunching at its centre.
data-absorb px · default 64
Capture radius for the sink force.
data-max number · default 60
Load at which a sink supernovas (releases).
data-fmin / data-fmax number
Variable-font weight range that --d drives on a feedback body.
data-opsz number
Optical-size axis to drive alongside weight.
data-active "1"
Engagement state — set automatically on hover/focus of a [data-hot] element.
data-preset name
Expand a preset into several co-located bodies — blackhole, galaxy, tornado, …

Which force reads which

Beyond the universal data-body / data-when / data-feedback, each force reads this subset (declared in the catalog):

Canonical
attract
data-strengthdata-range
repel
data-strengthdata-range
swirl
data-strengthdata-rangedata-spin
stream
data-strengthdata-rangedata-angle
viscosity
data-strengthdata-range
jet
data-strengthdata-rangedata-angle
tether
data-strengthdata-range
wall
box-sized — no params
sink
data-absorbdata-max
Natural
gravity
data-strengthdata-range
charge
data-strengthdata-rangedata-spin
magnetism
data-strengthdata-rangedata-spin
thermal
data-strengthdata-range
collide
data-strengthdata-range
diffuse
data-strengthdata-range
propagate
data-strengthdata-range
memory
data-strengthdata-range
Extended
lens
data-strengthdata-rangedata-spin
gate
data-angle
buoyancy
data-strengthdata-range
shear
data-strengthdata-rangedata-angle
crystallize
data-strengthdata-range
align
data-strengthdata-rangedata-angle
wind
data-strengthdata-range
cohesion
data-strengthdata-range
pressure
data-strengthdata-range
hunt
data-strengthdata-range
spawn
data-strengthdata-angle
link
data-strengthdata-range
morph
data-strengthdata-target
resonate
data-strengthdata-spin
spotlight
data-angle
pigment
data-rangedata-color
fieldflow
data-strengthdata-range

What the field writes back

Reciprocity has two halves: bodies bend the field through data-*, and the field bends them back through CSS custom properties. A body that opts in (data-feedback) receives these on its element — read them in your own CSS to make type glow, cards lift, or a meter fill. The write target is the element itself, or a body's writeTarget.

--d on data-feedback
The body's own gathered density ∈ [0,1], eased. The canonical reaction var.
--forces-density on data-feedback
Explicit alias of --d (the namespaced name; same value).
--forces-heatmap-density on data-feedback + heatmap
The ambient heatmap density under the body ∈ [0,1] — where matter pools around it, distinct from --d.
--load / --mass on sink body
A sink’s accretion fill fraction ∈ [0,1] (--mass is a back-compat alias).
--lit on causality
Spillover-lit density when a saturated neighbour bleeds density across a boundary.