dt-design-system/packages/hex-background/README.md

@dangerousthings/hex-background

3D hexagon grid background for the Dangerous Things design system. Renders an animated, instanced WebGL hex grid using Three.js and React Three Fiber. Hexagons animate to random heights on a loop, with a slowly orbiting camera.

Install

npm install @dangerousthings/hex-background

Peer Dependencies

npm install react @react-three/fiber three

For React Native, also install expo-gl.

Web Usage

Drop-in full-viewport background that renders behind page content:

import { HexGridBackground } from "@dangerousthings/hex-background";

function App() {
  return (
    <>
      <HexGridBackground />
      <main>{/* your content */}</main>
    </>
  );
}

The component renders a fixed-position Canvas at z-index: -1 with pointer-events: none, so it sits behind all other content. It automatically sizes the grid to the viewport and skips rendering in automated browsers (Selenium, Puppeteer).

Props

Prop	Type	Default	Description
opacity	number	0.5	Canvas opacity
hexRadius	number	0.5	Hexagon radius
margin	number	0.05	Spacing between hexagons
maxHeight	number	3	Maximum animation height
animationInterval	number	1500	Height target refresh interval in ms
cameraSpeed	number	0.02	Camera orbital speed
cameraRadius	number	8	Camera orbital radius
fov	number	40	Camera field of view

React Native Usage

The full-viewport HexGridBackground wrapper uses web-specific APIs. For React Native, use the lower-level HexGrid and HexCamera components directly within a native Canvas:

import { Canvas } from "@react-three/fiber/native";
import { HexGrid, HexCamera } from "@dangerousthings/hex-background/native";

function Background() {
  return (
    <Canvas camera={{ position: [5, 5, 5], fov: 40 }}>
      <HexCamera />
      <ambientLight intensity={20} />
      <directionalLight position={[20, 40, 20]} intensity={1.5} />
      <HexGrid rows={20} cols={20} />
    </Canvas>
  );
}

Exports

Path	Description
@dangerousthings/hex-background	HexGridBackground, HexGrid, HexCamera (web)
@dangerousthings/hex-background/native	HexGrid, HexCamera (React Native)

Monorepo

Part of the DT Design System monorepo.

License

MIT