GridDistortion
grid-distortionDistorts an image grid through a pointer-driven displacement field with elastic relaxation.
Usage
Basic usage
When imageSrc is not passed, chart token grid shading is programmatically generated, and ripples are launched by moving the mouse.
<div className="relative h-64 overflow-hidden rounded-xl bg-neutral-950">
<GridDistortion />
</div>High density + strong distortion
grid The higher the grid, the finer the grid and the smoother the ripples; the larger the strength is, the more intense the ripples are.
<GridDistortion grid={24} strength={0.3} mouse={0.18} />Long finish (high relaxation)
relaxation The closer it is to 1, the slower the ripple decay and the longer the aftertaste.
<GridDistortion relaxation={0.96} strength={0.2} />Customize the main color of the shading
color changes the main color of the grid shading (only effective when imageSrc is not uploaded).
<GridDistortion color="oklch(0.72 0.22 30)" grid={18} />When to Use
Use it for an interactive hero or landing-page grid that ripples as the pointer moves. Use GridPattern for static geometry, RetroGrid for a perspective horizon, or Spotlight for a pointer focus without deformation. GridDistortion can also apply the same velocity-driven displacement and relaxation to a supplied image.
Import
import { GridDistortion } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| grid | number | 15 | Number of displacement cells per side; JavaScript updates grid² cells per frame, with 8–30 recommended |
| mouse | number | 0.1 | Pointer influence radius relative to the grid; range = grid × mouse |
| strength | number | 0.15 | Displacement multiplier applied to pointer velocity; higher values produce stronger ripples |
| relaxation | number | 0.9 | Per-frame decay from 0 to 1; values closer to 1 make ripples persist longer |
| imageSrc | string | — | Image to distort. When omitted, a grid texture is generated from chart tokens (recommended). Supplied images must be same-origin or CORS-enabled. |
| color | string | --color-chart-1 | Main procedural-grid color used when imageSrc is omitted; accepts any CSS color |
| className | string | — | Root container (or div) |
Slots
| Slot | Type | Description |
|---|---|---|
| fallback | ReactNode | Static non-WebGL content for SSR, reduced motion, or unavailable WebGL; defaults to a shaded grid |
Usage Guidelines
- Render the OGL/WebGL effect inside a
"use client"boundary. SSR and unavailable WebGL render static mesh shading. - JavaScript performs O(
grid²) work per frame. Values above 30 noticeably increase CPU cost. - External
imageSrcassets must be same-origin or CORS-enabled, or the WebGL texture becomes tainted and cannot be read. - Place the root in a
relative overflow-hiddencontainer with an explicit height such ash-64. Distortion depends on pointer events and remains static on touch-only devices.
Related
DotPattern · GridPattern · StripedPattern · Spotlight · RetroGrid · Ripple
Playground
<div className="relative h-64 overflow-hidden rounded-xl"
style={{ background: "oklch(0.14 0.02 255)" }}>
<GridDistortion
grid={15}
mouse={0.1}
strength={0.15}
relaxation={0.9}
/>
</div>