Velocity Grid
An interactive WebGL component that displays media (image or video) with a fluid, 2D grid-based velocity distortion effect following the cursor.
Last Modified:Aug 17, 2026
Install
CLI
velocity-grid
Or install a specific demo variant:
velocity-grid-image
Or install a specific demo variant:
velocity-grid-video
Manual
1. Install Dependencies
Since this component leverages WebGL, you will need React Three Fiber and Three.js.
CLI Install
Note: The demos utilize @hugeicons/react and @hugeicons/core-free-icons for the loading fallback, but they are not strictly required for the core component.
2. Add Source Code
Props
| Prop | Type | Default | Description |
|---|---|---|---|
mediaUrl | string | — | The source URL of the media asset. |
mediaType | "image" | "video" | "image" | Defines the media type for correct texture processing. |
columns | number | 24 | Number of vertical grid columns. |
rows | number | 16 | Number of horizontal grid rows. |
hoverRadius | number | 0.35 | Proximity spread multiplier (0.0 to 1.0). |
shiftMultiplier | number | 1.5 | Strength of the displacement shift based on mouse velocity. |
trackingSpeed | number | 2.0 | Interpolation speed for the wave following the cursor. |
imageZoom | number | 1.15 | Base texture scale to prevent edge bleeding during displacement. |
enterLeaveSpeed | number | 1.5 | Interpolation speed for the enter/leave animation states. |
fallback | React.ReactNode | null | Optional fallback UI rendered via Suspense while media loads. |
className | string | undefined | Standard React classNames for the container wrapper. |