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-background
Registry item
Installs withuse-background-clockutils

Looking 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.

Nexus / Field systemsSeed 0042

03 / Cartography

Read between the lines.

A new perspective on the places we build. Quiet layers. Considered movement.

Terrain survey

Procedural design study

Reduced motion · static

Evolution reshapes ridges and valleys in a continuous noise field. Scan motion is independent.

Evolution amount65%
Speed1×
Cycle length48s
Travel14

Travel affects drift or bobbing only. Terrain evolution and scan/signal effects have their own controls.

Scan / signal speed1×

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.

Image intensity65%

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.

PropTypeDefaultDescription
variantGroundworkVariant"survey"survey: natural contours; cut-fill: terraced excavation; mesh: ground scan; exchange: connected sites.
seednumber42Reproducible terrain or site layout. Integer, 1–9999.
ruggednessnumber.55Contribution of fine terrain detail, 0–1.
densitynumber16Contour intervals, mesh resolution or number of sites; 6–24.
reliefnumber180Vertical exaggeration of the 3D terrain, 0–260.
bearingnumber45Orthographic camera bearing in degrees, 15–75.
terracesnumber7Number of stepped elevation bands in cut-and-fill, 3–16.
datumnumber.62Design elevation: ground above this level is cut and hatched, 0.2–1.
connectionsnumber2Nearest-neighbour links per site, 1–4; a spanning tree keeps all sites connected.
siteSizenumber1Material-exchange site glyph size, 0.5–2; independent of field extent.
animatedbooleantrueFalse renders the same geometry without motion.
pausedbooleanfalseFreeze the current frame without losing animation progress.
durationnumber48Cycle duration in seconds, 2–120.
speednumber1Playback multiplier, 0.25–6; cycles never run faster than two seconds.
amplitudenumber14Drift distance, 0–120; independent from scans and terrain evolution.
floatingbooleanfalseOptional vertical bobbing for the 3D studies; off by default.
surveyMotion"evolve" | "drift" | "still""evolve"Survey evolution changes the underlying noise field. Default: evolve.
evolutionAmountnumber.65Noise-field excursion during an evolution cycle, 0–2.
terrainFrequencynumber3.6Terrain feature frequency, 1–8.
terrainWarpnumber.85Ridge/valley distortion, 0–2.
extent"tile" | "field""tile"Model on a finite plate, or an extended field cropped to the viewport.
lineWeightnumber1Line weight multiplier, 0.4–2.5; preserves major/minor line hierarchy.
effectSpeednumber1Independent scan/signal speed multiplier, 0.25–4.
scalenumber1Composition zoom, clamped to 0.75–2.
opacitynumber.4Overall line and face opacity, clamped to 0–1.
colorstring"currentColor"Any CSS colour; defaults to the container's text colour.
accentColorstring"currentColor"Scan, excavation hatch and material signal colour. Defaults to currentColor.
showScanbooleantrueTravelling survey line or mesh scan highlights.
showGridbooleantrueReference grid and base plate.
showMarkersbooleantrueSurvey markers, elevation probes and site beacons.
showShadingbooleantrueFilled terrain faces; false leaves a wireframe.
showHatchingbooleantrueExcavation footprint hatching.
showDatumbooleantrueDashed design elevation plane.
showSignalsbooleantrueTravelling material signals.
showRoutesbooleantrueSite-to-site route lines.
classNamestring——