API reference

Every prop on the React component, the imperative handle, the TopoField class for vanilla use, and the two helper exports.

Props

Topolines accepts TopolinesOptions plus three React-only props. Every field is optional.

Prop	Type	Default	Description
seed	string	"topo"	Any string. Same seed produces the same starting pattern.
speed	number	0.012	Time multiplier. About 0.012 is roughly 10px/sec of contour drift; 0 freezes it.
scale	number	1.15	Noise frequency. Lower values give larger, sweepier landforms.
levels	number	11	Number of contour bands. More means denser line packing.
lineWidth	number	1.2	Line thickness in CSS pixels. Stays constant regardless of field steepness.
opacity	number	0.16	Line opacity.
color	string	"#C3D82C"	Line color, as a hex string.
drift	[number, number]	[0.004, 0.002]	Slow translation across the field, in units per second. Adds sideways drift.
warp	number	0.18	Domain warp strength. 0 is smooth blobs, about 0.2 is meandering and terrain-like.
scrollPan	[number, number]	[0, 0]	Noise units panned per scrolled pixel, [x, y]. Scrolling moves across the field so each section sits on a different part of the map.
colorStops	{ at: number; color: string; opacity: number }[]	undefined	Scroll-driven recoloring. at is progress from 0 to 1; color and opacity are lerped between the two nearest stops and hold at the nearest stop outside the band. Overrides color and opacity when set.
getProgress	() => number	document scroll progress	Supplies the 0 to 1 progress value colorStops reads. Use it to drive color from something other than whole-document scroll, such as one section's own progress.
getPanScroll	() => number	window.scrollY	Overrides the scroll value scrollPan reads. Lets the host freeze the map's travel across a range, such as a pinned section, by clamping scrollY.
maxDpr	number	1.5	Cap on devicePixelRatio. The effect is fragment-bound, so 1.5 is plenty even on dense screens.
interactive	boolean	false	When true, the field bulges toward the pointer as it moves.
mouseStrength	number	0.35	Peak height added under the cursor when interactive is on.
mouseRadius	number	0.35	Radius of the mouse bump, in the same noise-unit space as scale.
fallback	ReactNode	null	Rendered instead of the canvas when the browser cannot run the effect.
className	string	undefined	Passed to the host element.
style	React.CSSProperties	undefined	Passed to the host element.

Handle

Pass a ref to Topolines to get an imperative handle with four methods.

interface TopolinesHandle {
  play(): void;
  pause(): void;
  setClock(t: number): void;
  snapshot(): string | null;
}

play(): Resumes the animation loop.
pause(): Stops the loop; the field holds its current frame.
setClock(t): Sets the internal clock directly, for scrubbing to an exact time.
snapshot(): Draws one frame and returns it as a PNG data URL, or null if nothing has rendered yet.

TopoField

The class the React component wraps. Use it directly outside React.

class TopoField {
  constructor(host: HTMLElement, options: TopolinesOptions);
  readonly ok: boolean;
  setOptions(partial: Partial<TopolinesOptions>): void;
  play(): void;
  pause(): void;
  setClock(t: number): void;
  snapshot(): string | null;
  destroy(): void;
}

new TopoField(host, options): Mounts a fresh canvas inside host and starts the effect immediately.
.ok: False when WebGL or the derivatives extension is missing. When false, the constructor mounted nothing.
.setOptions(partial): Updates any subset of options live, without tearing down the GL context.
.play() / .pause() / .setClock(t) / .snapshot(): Same as the handle above.
.destroy(): Stops the loop, removes all listeners and observers, and removes the canvas.

isSupported, randomSeed

Two standalone functions, exported from the root of the package.

isSupported(): boolean: Probes for WebGL1 and the OES_standard_derivatives extension. The result is cached after the first call.
randomSeed(): string: Returns a random base36 string, useful behind a shuffle or dice button.

Presets

PRESETS is an array of six option sets, tuned on a dark #0D0D0B background. Each entry has an id, a name, and an options object you can spread onto Topolines or TopoField.

Id	Name	Notable options
01	Relief	color "#F2EFE6", opacity 0.34, warp 0.22
02	Ridgeline	scale 0.8, levels 8, lineWidth 1.6, color "#FF4D00", opacity 0.5, warp 0.3
03	Survey	scale 1.6, levels 18, lineWidth 0.8, color "#9EC7E8", opacity 0.4, warp 0.12
04	Basin	scale 0.6, levels 12, color "#C3D82C", opacity 0.42, warp 0.05, speed 0.02
05	Glass	warp 0, levels 7, lineWidth 2.2, color "#C9B8E8", opacity 0.3, speed 0.006
06	Drift	drift [0.02, 0.01], speed 0.03, levels 10, color "#A8B89A", opacity 0.38

import { PRESETS } from "topolines";
import { Topolines } from "topolines/react";

const relief = PRESETS[0];

<Topolines seed="hero" {...relief.options} />

← Docs and recipes