@abhiramkrishna/spacetime-grid

@abhiramkrishna/spacetime-grid

An animated three.js grid of tiles: idle waves roll across it, tiles sink into a gravity well under the cursor, and clicks send energy rings across the surface. It's the background of abhiramkrishna.com, packaged as a framework-agnostic component with Vue, React and Web Component wrappers.

Idle waves	Cursor gravity well
Click ripple	Custom theme

• One instanced mesh: 3,840 tiles by default, about 0.3 ms of CPU per frame in a 4×-CPU-throttled Chromium test.
• Pauses when the canvas is off-screen or the tab is hidden.
• Respects prefers-reduced-motion with a still frame.
• Plugins for scroll-driven camera moves, wells that follow elements, and data overlays.
• 28 options, all described by an exported schema you can build a settings UI from.

Install

npm install @abhiramkrishna/spacetime-grid three

three is a peer dependency (≥ 0.160), so the grid uses your app's copy. Vue (≥ 3.3) and React (≥ 18) are optional peers, needed only for their wrappers.

Quick start

import { SpacetimeGrid } from "@abhiramkrishna/spacetime-grid";

const grid = new SpacetimeGrid(document.getElementById("background")!);

Pass any element. The grid adds a canvas that fills it and follows its size, so give the element a size:

#background {
  position: fixed;
  inset: 0;
  z-index: -1;
}

You can also pass a <canvas> you already have. The grid listens for the mouse and clicks on window, so it keeps working behind your page content. Positions are mapped onto the canvas, and anything outside it is ignored.

Call grid.destroy() when you're done. It stops the loop, removes the listeners and frees the GPU resources.

Options

const grid = new SpacetimeGrid(el, {
  cols: 80,
  waveAmplitude: 0.12,
  wellRadius: 3,
  theme: { base: "#123a55", hover: "#5ee6ff", fog: "#04223a", fresnel: "#d8f4ff" },
});

grid.setOptions({ rippleSpeed: 3.5, theme: { hover: "#ff9e7a" } });

Options marked live can be changed at any time with setOptions. The others (cols, rows, cellSize, fill) set the size of the tile mesh, so to change them, create a new grid. The wrappers below do that for you.

Theme. theme.fog should match the page background, so tiles fade into it.

Grid

Waves

Gravity well

Ripples

Colours

Fog

Camera

Rendering

SPACETIME_GRID_SCHEMA exports the table above as data, one entry per option: key, label, group, type, default, min/max/step or choices, description and live. DEFAULT_SETTINGS and DEFAULT_THEME hold the defaults.

Reduced motion

By default (reducedMotion: "auto"), visitors with prefers-reduced-motion: reduce get a single still frame. It's redrawn on resize, theme changes and plugin changes, but it never animates, and the cursor and clicks do nothing. If the visitor changes the setting while the page is open, the grid switches over. Use "always" to force the still frame, or "never" to always animate.

Wrappers

Every option is a prop. Each wrapper also takes theme and plugins, and gives you the SpacetimeGrid instance. Live props update the grid in place. Changing cols, rows, cellSize or fill rebuilds it.

Vue

<script setup lang="ts">
import { SpacetimeGrid } from "@abhiramkrishna/spacetime-grid/vue";
import type { SpacetimeGrid as Grid } from "@abhiramkrishna/spacetime-grid";

function onReady(grid: Grid) {
  grid.ripple(innerWidth / 2, innerHeight / 2);
}
</script>

<template>
  <div class="background">
    <SpacetimeGrid :wave-amplitude="0.12" :theme="{ hover: '#5ee6ff' }" @ready="onReady" />
  </div>
</template>

A template ref on the component exposes grid.

React

import { useRef } from "react";
import { SpacetimeGrid } from "@abhiramkrishna/spacetime-grid/react";
import type { SpacetimeGrid as Grid } from "@abhiramkrishna/spacetime-grid";

export function Background() {
  const grid = useRef<Grid>(null);
  return (
    <div className="background">
      <SpacetimeGrid ref={grid} waveAmplitude={0.12} theme={{ hover: "#5ee6ff" }} />
    </div>
  );
}

It also accepts className, style and onReady. Keep the plugins array stable (for example with useMemo), because a new array re-adds the plugins.

Web Component

import { defineSpacetimeGridElement } from "@abhiramkrishna/spacetime-grid/element";

defineSpacetimeGridElement();

<spacetime-grid wave-amplitude="0.12" theme-hover="#5ee6ff" style="position: fixed; inset: 0"></spacetime-grid>

• Registration: nothing is registered until you call defineSpacetimeGridElement(tagName?), so importing the module has no side effects and is safe during server rendering.
• Attributes: options are kebab-case attributes (wave-amplitude, cursor-well="false"). Theme colours are theme-base, theme-hover, theme-fog and theme-fresnel.
• Properties: el.options = { … } sets options from JavaScript, and el.use(plugin) adds a plugin.
• Instance: el.grid is the instance, and a ready event fires each time one is created.

Plugins

Plugins hook into each frame. Two come with the package.

scrollCamera: fly between camera poses as the page scrolls

import { SpacetimeGrid, scrollCamera } from "@abhiramkrishna/spacetime-grid";

const poses = {
  hero: { position: [0, 1.3, 6], lookAt: [0, -1, -3] },
  about: { position: [1.7, 1.15, 5], lookAt: [1.4, -1, -3] },
} as const;

grid.use(scrollCamera({
  poses,
  initial: "hero",
  segments: () => [{ from: "hero", to: "about", start: 0, end: window.innerHeight }],
}));

• segments is called every frame, so it can read fresh section offsets.
• Between start and end (scroll pixels), the camera eases from one pose to the next, and the grid smooths the move by cameraEase.
• To drive it from something other than window.scrollY, pass scroll: () => number.
• With reduced motion, the camera stays on initial.

elementWell: a gravity well that follows an element

import { elementWell } from "@abhiramkrishna/spacetime-grid";

grid.use(elementWell(() => document.querySelector(".dialog"), {
  radius: 4.2,
  depth: 1.15,
  strength: () => dialogProgress,
}));

The well sits under the element's centre. strength scales its depth; at 0 or below, the well is off.

Impulses

For a one-off ripple at a screen point, such as an object landing on the grid, call:

grid.ripple(clientX, clientY, 1.4);

Writing a plugin

import type { GridPlugin } from "@abhiramkrishna/spacetime-grid";

const tile = 30 * grid.cols + 32;

const pulse: GridPlugin = {
  setup(g) {
    return () => g.glow.fill(0);
  },
  beforeFrame({ t }) {
    grid.glow[tile] = 0.5 + 0.5 * Math.sin(t * 2);
  },
};

const remove = grid.use(pulse);

All four hooks are optional: setup(grid) (return a cleanup function), beforeFrame(frame), afterFrame(frame) and themeChanged({ base, hover }), which is called once when the plugin is added and again on every theme change. Each frame runs in this order:

1. beforeFrame: set camera targets, add wells, write glow.
2. The camera eases.
3. The tiles update.
4. afterFrame: read grid.heights to place meshes on the tiles.
5. The frame renders.

frame is { t, dt, motion }, and dt is capped at 0.05 s. Add your own meshes to grid.group; its local XY plane is the grid surface. Keep per-frame work allocation-free, because the grid runs every frame.

API

new SpacetimeGrid(target, options?)

target is an HTMLElement (a canvas is added to it) or an HTMLCanvasElement.

Performance notes

• Idle waves: precomputed per-tile sine and cosine, combined each frame by angle addition, so there are no trig calls per tile per frame.
• Tile loop: writes straight into the instance buffers and allocates nothing.
• Pausing: the loop pauses off-screen and in hidden tabs. Its clock pauses too, so the animation resumes where it stopped.
• Pixel ratio: capped by maxPixelRatio (default 2).

License

MIT © Abhiram Krishna M