Search nx-ui
Jump to any foundation, component, block or example.
Living backgrounds
Landscapes, layers and connections. Six architectural studies, made to live behind your interface.
bunx shadcn@latest add @nx-ui/groundwork-backgroundLooking for the simulation? Explore the Living material network.
Choose a direction
Two original studies, four new territories. Select a study to explore its behaviour.
The playground
A seeded elevation field with warped ridgelines, branching valleys and a travelling survey line.
03 / Cartography
Read between the lines.
A new perspective on the places we build. Quiet layers. Considered movement.
Terrain survey
Procedural design study
Evolution reshapes ridges and valleys in a continuous noise field. Scan motion is independent.
Travel affects drift or bobbing only. Terrain evolution and scan/signal effects have their own controls.
Pause freezes drift, tours and pointer response. Static and reduced motion restore the base pose. Tours also pause offscreen and in hidden tabs.
Still, by design
Every direction has a static version. These follow your procedural settings and use each study’s default intensity.
Contours
Static fallback
Ribbons
Static fallback
Terrain survey
Static fallback
Cut & fill
Static fallback
Ground scan
Static fallback
Material exchange
Static fallback
The original studies
The four generated raster textures on your selected surface. The six living studies are independently drawn SVGs.
Study 01
Organic contours
Study 02
Flowing bands
Study 03
Technical contours
Study 04
Sparse contours
Use a landscape
A transparent decorative layer, with content above it and a visible pause control for ongoing motion. Colour inherits from the container; accentColor optionally tints scans and signals.
import { useState } from "react"
import { GroundworkBackground } from "@/components/blocks/groundwork-background/groundwork-background"
export function BackgroundExample() {
const [paused, setPaused] = useState(false)
return <div
className="relative min-h-96 overflow-hidden bg-primary text-primary-foreground"
>
<GroundworkBackground
variant="survey"
seed={42}
ruggedness={0.55}
density={16}
relief={180}
bearing={45}
terraces={7}
datum={0.62}
connections={2}
duration={48}
speed={1}
amplitude={14}
scale={1}
opacity={0.48}
animated={true}
floating={false}
surveyMotion="evolve"
evolutionAmount={0.65}
terrainFrequency={3.6}
terrainWarp={0.85}
extent="tile"
effectSpeed={1}
lineWeight={1}
siteSize={1}
showScan={true}
showGrid={true}
showMarkers={true}
showShading={true}
showHatching={true}
showDatum={true}
showRoutes={true}
showSignals={true}
paused={paused}
/>
<div className="relative z-10 p-6">
<button onClick={() => setPaused(value => !value)}>{paused ? "Play" : "Pause"}</button>
</div>
</div>
}Use animated=false for a static fallback. The optional motion controller provides looping tours and pointer interaction, with reduced-motion, visibility and pause handling. Geometry stays seeded and repeatable.
API reference
Exported parts and their props, extracted from the component source.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | GroundworkVariant | "survey" | survey: natural contours; cut-fill: terraced excavation; mesh: ground scan; exchange: connected sites. |
seed | number | 42 | Reproducible terrain or site layout. Integer, 1–9999. |
ruggedness | number | .55 | Contribution of fine terrain detail, 0–1. |
density | number | 16 | Contour intervals, mesh resolution or number of sites; 6–24. |
relief | number | 180 | Vertical exaggeration of the 3D terrain, 0–260. |
bearing | number | 45 | Orthographic camera bearing in degrees, 15–75. |
terraces | number | 7 | Number of stepped elevation bands in cut-and-fill, 3–16. |
datum | number | .62 | Design elevation: ground above this level is cut and hatched, 0.2–1. |
connections | number | 2 | Nearest-neighbour links per site, 1–4; a spanning tree keeps all sites connected. |
siteSize | number | 1 | Material-exchange site glyph size, 0.5–2; independent of field extent. |
animated | boolean | true | False renders the same geometry without motion. |
paused | boolean | false | Freeze the current frame without losing animation progress. |
duration | number | 48 | Cycle duration in seconds, 2–120. |
speed | number | 1 | Playback multiplier, 0.25–6; cycles never run faster than two seconds. |
amplitude | number | 14 | Drift distance, 0–120; independent from scans and terrain evolution. |
floating | boolean | false | Optional vertical bobbing for the 3D studies; off by default. |
surveyMotion | "evolve" | "drift" | "still" | "evolve" | Survey evolution changes the underlying noise field. Default: evolve. |
evolutionAmount | number | .65 | Noise-field excursion during an evolution cycle, 0–2. |
terrainFrequency | number | 3.6 | Terrain feature frequency, 1–8. |
terrainWarp | number | .85 | Ridge/valley distortion, 0–2. |
extent | "tile" | "field" | "tile" | Model on a finite plate, or an extended field cropped to the viewport. |
lineWeight | number | 1 | Line weight multiplier, 0.4–2.5; preserves major/minor line hierarchy. |
effectSpeed | number | 1 | Independent scan/signal speed multiplier, 0.25–4. |
scale | number | 1 | Composition zoom, clamped to 0.75–2. |
opacity | number | .4 | Overall line and face opacity, clamped to 0–1. |
color | string | "currentColor" | Any CSS colour; defaults to the container's text colour. |
accentColor | string | "currentColor" | Scan, excavation hatch and material signal colour. Defaults to currentColor. |
showScan | boolean | true | Travelling survey line or mesh scan highlights. |
showGrid | boolean | true | Reference grid and base plate. |
showMarkers | boolean | true | Survey markers, elevation probes and site beacons. |
showShading | boolean | true | Filled terrain faces; false leaves a wireframe. |
showHatching | boolean | true | Excavation footprint hatching. |
showDatum | boolean | true | Dashed design elevation plane. |
showSignals | boolean | true | Travelling material signals. |
showRoutes | boolean | true | Site-to-site route lines. |
className | string | — | — |