Documentation
API reference for @shapesoup/core
Quick Start
ShapeSoup is a pure TypeScript package with zero browser dependencies. Install it and generate your first SVG in seconds.
pnpm add @shapesoup/core
# or
npm install @shapesoup/coreimport { generateBlobScene } from "@shapesoup/core";
const result = generateBlobScene({
width: 1200,
height: 800,
seed: "my-product-launch",
});
console.log(result.svg); // raw SVG string
console.log(result.dataUri); // data:image/svg+xml,...
console.log(result.metadata); // { generator, seed, width, height, elements }Every generator is deterministic: the same config + seed always produces the same SVG output.
Base Types
BaseGeneratorConfig
Shared by all generators.
type BaseGeneratorConfig = {
width: number;
height: number;
seed?: string | number;
background?: string;
colors?: string[];
};GeneratorOutput
What every generator returns.
type GeneratorOutput = {
svg: string;
dataUri: string;
metadata: {
generator: string;
seed: string;
width: number;
height: number;
elements: number;
};
};GeneratorType
String union for the generic dispatcher.
type GeneratorType =
| "blob"
| "wave"
| "blurryGradient"
| "blobScene"
| "layeredWaves"
| "stackedWaves"
| "lowPolyGrid"
| "layeredPeaks"
| "topoLines"
| "dotMatrix"
| "meshGradient"
| "noiseGrid"
| "bauhausPattern";Generators
13 deterministic SVG generators. Each accepts a config object and returns a GeneratorOutput.
generateBlob
A single organic blob shape with smooth curves.
type BlobConfig = {
width: number;
height: number;
seed?: string | number;
complexity?: number; // default: 8
contrast?: number; // default: 0.4
colors?: string[]; // default: ["#6366f1", "#a855f7", "#ec4899"]
};generateWave
A single sine wave with organic variation.
type WaveConfig = {
width: number;
height: number;
seed?: string | number;
amplitude?: number; // default: 80
frequency?: number; // default: 0.01
points?: number; // default: 10
layerCount?: number; // default: 4
colors?: string[]; // default: ["#0ea5e9", "#6366f1", "#a855f7"]
};generateLayeredWaves
Multiple smooth wave layers stacked vertically.
Uses WaveConfig. layerCount controls the number of stacked smooth wave layers.
generateStackedWaves
Multiple sharp wave layers stacked vertically.
Uses WaveConfig. layerCount controls the number of stacked sharp wave layers.
generateBlurryGradient
Soft blurred blob gradients with SVG filters.
type BlurryGradientConfig = {
width: number;
height: number;
seed?: string | number;
blobCount?: number; // default: 5
blurAmount?: number; // default: 40
colors?: string[]; // default: ["#f43f5e", "#f97316", "#eab308"]
};generateBlobScene
Organic solid blob compositions with layered contour bands.
type BlobSceneConfig = {
width: number;
height: number;
seed?: string | number;
groupCount?: number; // default: 2
layersPerGroup?: number; // default: 5
complexity?: number; // default: 12
contrast?: number; // default: 0.3
size?: number; // default: 1.2
colors?: string[]; // default: ["#0f766e", "#14b8a6", "#5eead4", "#ccfbf1"]
};generateLowPolyGrid
Triangulated geometric color fields with jitter.
type LowPolyGridConfig = {
width: number;
height: number;
seed?: string | number;
cols?: number; // default: 8
rows?: number; // default: 6
jitter?: number; // default: 0.4
colors?: string[]; // default: ["#f43f5e", "#f97316", "#eab308", "#84cc16"]
};generateLayeredPeaks
Mountain-like layered peak silhouettes.
type LayeredPeaksConfig = {
width: number;
height: number;
seed?: string | number;
layerCount?: number; // default: 5
peakCount?: number; // default: 8
roughness?: number; // default: 0.4
colors?: string[]; // default: ["#1e293b", "#334155", "#475569", "#64748b", "#94a3b8"]
};generateTopoLines
Contour-map style organic line patterns.
type TopoLinesConfig = {
width: number;
height: number;
seed?: string | number;
lineCount?: number; // default: 12
amplitude?: number; // default: 60
frequency?: number; // default: 0.008
noise?: number; // default: 0.5
strokeWidth?: number; // default: 1.5
spacing?: number; // default: 50
colors?: string[]; // default: ["#1e293b", "#38bdf8", "#a78bfa", "#f472b6"]
backgroundColor?: string; // default: "#f8fafc"
};generateDotMatrix
Seeded halftone-style dot fields with distance-based radii.
type DotMatrixConfig = {
width: number;
height: number;
seed?: string | number;
columns?: number; // default: 16
rows?: number; // default: 12
minRadius?: number; // default: 2
maxRadius?: number; // default: 20
jitter?: number; // default: 0.3
density?: number; // default: 0.85
colors?: string[]; // default: ["#0f172a", "#334155", "#64748b", "#94a3b8"]
backgroundColor?: string; // default: "#f1f5f9"
};generateMeshGradient
Soft modern gradient blobs with SVG blur filters.
type MeshGradientConfig = {
width: number;
height: number;
seed?: string | number;
blobCount?: number; // default: 6
blur?: number; // default: 50
opacity?: number; // default: 0.7
minRadius?: number; // default: 120
maxRadius?: number; // default: 350
colors?: string[]; // default: ["#c084fc", "#818cf8", "#38bdf8", "#2dd4bf", "#f472b6"]
backgroundColor?: string; // default: "#0f172a"
};generateNoiseGrid
Geometric texture with mixed shapes and jitter.
type NoiseGridConfig = {
width: number;
height: number;
seed?: string | number;
cellSize?: number; // default: 30
density?: number; // default: 0.6
shapeSize?: number; // default: 0.7
jitter?: number; // default: 0.4
strokeWidth?: number; // default: 1.5
colors?: string[]; // default: ["#1e293b", "#475569", "#94a3b8", "#cbd5e1"]
backgroundColor?: string; // default: "#f8fafc"
};generateBauhausPattern
Playful geometric poster layouts with bold shapes.
type BauhausPatternConfig = {
width: number;
height: number;
seed?: string | number;
shapeCount?: number; // default: 18
minSize?: number; // default: 30
maxSize?: number; // default: 180
strokeWidth?: number; // default: 3
colors?: string[]; // default: ["#dc2626", "#2563eb", "#f59e0b", "#1f2937", "#f3f4f6"]
backgroundColor?: string; // default: "#fef3c7"
allowStrokeOnly?: boolean; // default: true
};Generic Dispatcher
Use generatePattern to route to any generator by type string.
import { generatePattern } from "@shapesoup/core";
const result = generatePattern({
type: "layeredPeaks",
config: {
width: 800,
height: 600,
seed: "peaks",
layerCount: 5,
colors: ["#1e293b", "#334155", "#475569"],
},
});Presets
Color Palettes
Built-in curated palettes and palette generators.
import { presetPalettes, getRandomPalette, generateRandomPalette } from "@shapesoup/core";
// 12 named palettes
console.log(presetPalettes);
// Pick a random preset palette
const palette = getRandomPalette(rng.random);
// Generate a random HSL palette
const randomPalette = generateRandomPalette(rng.random, 5);Canvas Sizes
Common dimensions for quick reference.
import { canvasSizePresets } from "@shapesoup/core";
// [ { width: 800, height: 600 }, { width: 1200, height: 800 }, ... ]Utilities
createSeededRandom
Deterministic pseudo-random number generator. All generators use this internally.
import { createSeededRandom } from "@shapesoup/core";
const rng = createSeededRandom("my-seed");
rng.random(); // [0, 1)
rng.randomInt(0, 10); // integer in range
rng.randomFloat(0, 1); // float in range
rng.pick(["a", "b", "c"]); // random array elementColor Helpers
Palette interpolation and color utilities.
import { interpolatePalette, randomColorFromPalette, svgToDataUri } from "@shapesoup/core";
// Interpolate between palette colors in OKLab space
const color = interpolatePalette(["#ff0000", "#0000ff"], 0.5);
// Pick a random color from a palette
const random = randomColorFromPalette(palette, rng.random);
// Convert an SVG string to a data URI
const dataUri = svgToDataUri(svgString);same config + same seed = same SVG
Every generator is a pure function. The output depends only on the config and seed. This makes patterns cacheable, testable, and version-controllable.