358ecb05cb
- Add author, repository, homepage, keywords, and engines fields to all 6 publishable package.json files - Add README.md to react, tailwind-preset, and hex-background packages - Add "type": "module" to web and react-native for consistency - Rename web build script to .cjs for ESM package compatibility - Remove overly broad "./dist/*" export from web package Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
85 lines
2.5 KiB
Markdown
85 lines
2.5 KiB
Markdown
# @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
|
|
|
|
```bash
|
|
npm install @dangerousthings/hex-background
|
|
```
|
|
|
|
### Peer Dependencies
|
|
|
|
```bash
|
|
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:
|
|
|
|
```tsx
|
|
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:
|
|
|
|
```tsx
|
|
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](https://github.com/nicholasgriffintn/dt-design-system) monorepo.
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|