# Dot Grid

Aperveil / Light, shaped for the web.

A responsive dot grid background for React. Set spacing in CSS pixels, add a local cursor ripple, and export the WebGPU effect with your chosen colors.

[Aperveil integration guide](https://www.aperveil.com/docs)

## What it does

Pixel-sized dots move locally around the pointer without clipping at cell borders. Surface waves, repulsion and wave damping retain the grid structure and its automatic CSS-pixel spacing.

## Choose it for

Add a quiet technical texture to a developer-tool homepage. Keep the points small and place real HTML labels above the canvas; the grid supplies atmosphere, not information.

## Limits

This is analytic displacement with smoothed pointer input, not a particle collision simulation.

## Current look

Default. Color Looks change colors only; motion, geometry and typography remain unchanged.

[Open editor](https://www.aperveil.com/shaders/dot-grid/edit?look=default)

## Install

Download the Export Kit from the editor. No shader-specific npm package or CLI is published yet.

```sh
npm install ./vendor/aperveil-runtime-0.1.0.tgz ./vendor/aperveil-react-0.1.0.tgz
```

Every control in the editor is a typed prop. Leave a prop out to keep the value you exported; change one and the running shader updates without restarting. Give the surface a size and pass fallback for browsers without WebGPU.

```tsx
"use client";

import DotGrid from "./DotGrid";

export default function Hero() {
  return (
    <DotGrid
      className="hero-shader"
      density={72} background="#0d1017ff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

// .hero-shader { width: 100%; height: 560px; }
```

Component props: `background`, `dotColor`, `accentColor`, `density`, `dotSize`, `glow`, `flowSpeed`, `breathe`, `rippleStrength`, `rippleReach`, `autoSize`, `spacing`, `opacity`, `backgroundOpacity`, `repulsion`, `returnSpeed`, `waveAmount`, `className`, `style`, `paused`, `fallback`, `onReady`, `onError`.

Raw WGSL is included for a custom WebGPU host; it is not CSS. Keep semantic headings and links in HTML.

## Controls

- Background (`background`, color): Colour behind the dots.
- Dots (`dotColor`, color): Colour of the dots at rest.
- Accent (`accentColor`, color): Colour the dots take on near the cursor.
- Density (`density`, slider): Rows of dots when automatic sizing is off.
- Dot size (`dotSize`, slider): Size of each dot relative to the spacing between them.
- Accent falloff (`glow`, slider): How strongly dots take the accent colour near the cursor.
- Flow speed (`flowSpeed`, slider): Speed of the idle breathing and the ripple.
- Breathing (`breathe`, slider): Idle size wave, independent of the pointer.
- Ripple (`rippleStrength`, slider): How much dots swell in the ripple around the cursor.
- Ripple reach (`rippleReach`, slider): Radius of the pointer's influence, in canvas units.
- Automatic sizing (`autoSize`, checkbox): On: dots keep a fixed spacing in pixels, so bigger canvases show more of them. Off: a fixed number of rows (Density) scales with the canvas.
- Dot spacing (`spacing`, slider): Distance between dots in CSS pixels, used while automatic sizing is on.
- Opacity (`opacity`, slider): Opacity of the complete effect, including its background.
- Background opacity (`backgroundOpacity`, slider): Fade the background independently for transparent overlays.
- Repulsion (`repulsion`, slider): How far dots are pushed away from the cursor.
- Recovery & damping (`returnSpeed`, slider): How quickly the disturbance around the cursor settles; higher values give a tighter, faster wave.
- Surface wave (`waveAmount`, slider): Strength of the rippling wave that spreads from the cursor.

## Compatibility

WebGPU rendering requires a supported browser and secure context. The landing shows a real poster for the selected Look when live rendering is unavailable. The standard exported component does not bundle a poster fallback. Supply your own fallback in the host layout. Text exports also retain readable HTML typography.

## Performance

No published timing sample. Profile this effect on your target devices.

## Questions

### Will the dots become oversized on a large monitor?

Keep Auto size enabled and adjust Spacing in the editor. The grid uses CSS dimensions to maintain spacing as its container grows. Manual density remains available.

### What should I not use Dot Grid for?

The points are procedural pixels, not DOM elements. They do not represent data, accept individual click handlers or require a dot-per-element layout.

### What happens without WebGPU?

This landing shows a still poster of your selected Color Look. The raw WGSL needs a WebGPU host. Landing posters are not bundled in the Export Kit: add your own fallback around the exported component.

### Can I use this shader commercially?

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## License

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## Related shaders

- [Line Waves](https://www.aperveil.com/shaders/line-waves)
- [Hex Tiles](https://www.aperveil.com/shaders/hex-tiles)
- [Flip Tiles](https://www.aperveil.com/shaders/flip-tiles)