React Grid Distortion Background

React grid distortion background with Three.js shader effects. Features mouse-responsive image warping, customizable grid density, and fluid distortion patterns for dynamic visual experiences.

React

Three.js

WebGL

Creating interactive image distortions?

Join our Discord community for help from other developers working with Three.js shaders and image manipulation effects.

Ever wanted to create those mesmerizing image distortion effects where your cursor seems to ripple and warp the image like it's liquid? Those fluid interactions where mouse movement creates dynamic waves that propagate and decay naturally, transforming static images into living, responsive canvases? The way the distortion follows your movement with realistic physics-like behavior that feels organic and satisfying? Most image effects rely on simple CSS transforms or filters, but they lack the sophisticated grid-based displacement that creates truly immersive visual experiences.

This React component creates that captivating grid distortion effect using Three.js with custom shaders, featuring mouse-responsive image warping, configurable grid density, and smooth relaxation physics that bring dynamic fluidity to any image.

Mouse-responsive image warping with grid displacement

Watch images ripple and distort in real-time following your cursor with fluid physics:

Loading component...

// @ts-nocheck'use client';import React, { useRef, useEffect, forwardRef } from "react";import * as THREE from "three";import { cn } from '@/lib/utils';const vertexShader = `uniform float time;varying vec2 vUv;varying vec3 vPosition;void main() {  vUv = uv;  vPosition = position;  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);}`;const fragmentShader = `uniform sampler2D uDataTexture;uniform sampler2D uTexture;uniform vec4 resolution;varying vec2 vUv;void main() {  vec2 uv = vUv;  vec4 offset = texture2D(uDataTexture, vUv);  gl_FragColor = texture2D(uTexture, uv - 0.02 * offset.rg);}`;export interface GridDistortionProps extends React.HTMLAttributes<HTMLDivElement> {  grid?: number;  mouse?: number;  strength?: number;  relaxation?: number;  imageSrc: string;}export const GridDistortion = forwardRef<HTMLDivElement, GridDistortionProps>(({  className,  grid = 15,  mouse = 0.1,  strength = 0.15,  relaxation = 0.9,  imageSrc,  ...props}, ref) => {  const domProps = { ...props };  delete domProps.grid;  delete domProps.mouse;  delete domProps.strength;  delete domProps.relaxation;  delete domProps.imageSrc;  const containerRef = useRef<HTMLDivElement>(null);  const sceneRef = useRef<THREE.Scene | null>(null);  const rendererRef = useRef<THREE.WebGLRenderer | null>(null);  const cameraRef = useRef<THREE.OrthographicCamera | null>(null);  const planeRef = useRef<THREE.Mesh | null>(null);  const imageAspectRef = useRef<number>(1);  const animationIdRef = useRef<number | null>(null);  const resizeObserverRef = useRef<ResizeObserver | null>(null);  useEffect(() => {    if (!containerRef.current) return;    const container = containerRef.current;        const scene = new THREE.Scene();    sceneRef.current = scene;        const renderer = new THREE.WebGLRenderer({      antialias: true,      alpha: true,      powerPreference: "high-performance",    });    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));    renderer.setClearColor(0x000000, 0);    rendererRef.current = renderer;        container.innerHTML = '';    container.appendChild(renderer.domElement);    const camera = new THREE.OrthographicCamera(0, 0, 0, 0, -1000, 1000);    camera.position.z = 2;    cameraRef.current = camera;    const uniforms = {      time: { value: 0 },      resolution: { value: new THREE.Vector4() },      uTexture: { value: null as THREE.Texture | null },      uDataTexture: { value: null as THREE.DataTexture | null },    };    const textureLoader = new THREE.TextureLoader();    textureLoader.load(imageSrc, (texture) => {      texture.minFilter = THREE.LinearFilter;      texture.magFilter = THREE.LinearFilter;      texture.wrapS = THREE.ClampToEdgeWrapping;      texture.wrapT = THREE.ClampToEdgeWrapping;      imageAspectRef.current = texture.image.width / texture.image.height;      uniforms.uTexture.value = texture;      handleResize();    });    const size = grid;    const data = new Float32Array(4 * size * size);    for (let i = 0; i < size * size; i++) {      data[i * 4] = Math.random() * 255 - 125;      data[i * 4 + 1] = Math.random() * 255 - 125;    }    const dataTexture = new THREE.DataTexture(      data,      size,      size,      THREE.RGBAFormat,      THREE.FloatType    );    dataTexture.needsUpdate = true;    uniforms.uDataTexture.value = dataTexture;    const material = new THREE.ShaderMaterial({      side: THREE.DoubleSide,      uniforms,      vertexShader,      fragmentShader,      transparent: true,    });        const geometry = new THREE.PlaneGeometry(1, 1, size - 1, size - 1);    const plane = new THREE.Mesh(geometry, material);    planeRef.current = plane;    scene.add(plane);    const handleResize = () => {      if (!container || !renderer || !camera) return;            const rect = container.getBoundingClientRect();      const width = rect.width;      const height = rect.height;            if (width === 0 || height === 0) return;            const containerAspect = width / height;      renderer.setSize(width, height);      if (plane) {        plane.scale.set(containerAspect, 1, 1);      }      const frustumHeight = 1;      const frustumWidth = frustumHeight * containerAspect;      camera.left = -frustumWidth / 2;      camera.right = frustumWidth / 2;      camera.top = frustumHeight / 2;      camera.bottom = -frustumHeight / 2;      camera.updateProjectionMatrix();      uniforms.resolution.value.set(width, height, 1, 1);    };    if (window.ResizeObserver) {      const resizeObserver = new ResizeObserver(() => {        handleResize();      });      resizeObserver.observe(container);      resizeObserverRef.current = resizeObserver;    } else {      window.addEventListener("resize", handleResize);    }    const mouseState = {      x: 0,      y: 0,      prevX: 0,      prevY: 0,      vX: 0,      vY: 0,    };    const handleMouseMove = (e: MouseEvent) => {      const rect = container.getBoundingClientRect();      const x = (e.clientX - rect.left) / rect.width;      const y = 1 - (e.clientY - rect.top) / rect.height;      mouseState.vX = x - mouseState.prevX;      mouseState.vY = y - mouseState.prevY;      Object.assign(mouseState, { x, y, prevX: x, prevY: y });    };    const handleMouseLeave = () => {      if (dataTexture) {        dataTexture.needsUpdate = true;      }      Object.assign(mouseState, {        x: 0,        y: 0,        prevX: 0,        prevY: 0,        vX: 0,        vY: 0,      });    };    container.addEventListener("mousemove", handleMouseMove);    container.addEventListener("mouseleave", handleMouseLeave);    handleResize();    const animate = () => {      animationIdRef.current = requestAnimationFrame(animate);            if (!renderer || !scene || !camera) return;            uniforms.time.value += 0.05;      if (!(dataTexture.image.data instanceof Float32Array)) {        console.error("dataTexture.image.data is not a Float32Array");        return;      }      const data: Float32Array = dataTexture.image.data;      for (let i = 0; i < size * size; i++) {        data[i * 4] *= relaxation;        data[i * 4 + 1] *= relaxation;      }      const gridMouseX = size * mouseState.x;      const gridMouseY = size * mouseState.y;      const maxDist = size * mouse;      for (let i = 0; i < size; i++) {        for (let j = 0; j < size; j++) {          const distSq =            Math.pow(gridMouseX - i, 2) + Math.pow(gridMouseY - j, 2);          if (distSq < maxDist * maxDist) {            const index = 4 * (i + size * j);            const power = Math.min(maxDist / Math.sqrt(distSq), 10);            data[index] += strength * 100 * mouseState.vX * power;            data[index + 1] -= strength * 100 * mouseState.vY * power;          }        }      }      dataTexture.needsUpdate = true;      renderer.render(scene, camera);    };        animate();    return () => {      if (animationIdRef.current) {        cancelAnimationFrame(animationIdRef.current);      }            if (resizeObserverRef.current) {        resizeObserverRef.current.disconnect();      } else {        window.removeEventListener("resize", handleResize);      }            container.removeEventListener("mousemove", handleMouseMove);      container.removeEventListener("mouseleave", handleMouseLeave);            if (renderer) {        renderer.dispose();        if (container.contains(renderer.domElement)) {          container.removeChild(renderer.domElement);        }      }            if (geometry) geometry.dispose();      if (material) material.dispose();      if (dataTexture) dataTexture.dispose();      if (uniforms.uTexture.value) uniforms.uTexture.value.dispose();            sceneRef.current = null;      rendererRef.current = null;      cameraRef.current = null;      planeRef.current = null;    };  }, [grid, mouse, strength, relaxation, imageSrc]);  return (    <div      ref={ref}      className={cn("relative overflow-hidden w-full h-full", className)}      {...domProps}    >      <div        ref={containerRef}        className="w-full h-full"        style={{           minWidth: '0',          minHeight: '0'        }}      />    </div>  );});GridDistortion.displayName = 'GridDistortion';export default GridDistortion;

Built for React applications with TypeScript and optimized Three.js rendering. Uses custom fragment shaders for grid-based displacement while providing intuitive controls for distortion strength, mouse sensitivity, and relaxation timing. Perfect for hero sections, portfolio showcases, or any interface needing sophisticated image interaction effects.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/grid-distortion.json

npx shadcn@latest add https://www.shadcn.io/registry/grid-distortion.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/grid-distortion.json

bunx shadcn@latest add https://www.shadcn.io/registry/grid-distortion.json

Why static images feel lifeless

Developers add CSS hover effects to images and consider them interactive. Maybe they include some basic transforms or opacity changes. The problem? Static image effects can't capture the organic, fluid nature of truly responsive visuals that react dynamically to user interaction with realistic physics behavior.

Grid-based image distortion with WebGL shaders changes everything. It taps into our fascination with liquid dynamics—the way distortions propagate through space, how energy dissipates naturally over time, the hypnotic flow that makes digital surfaces feel tangible. The mathematical algorithms use grid displacement and relaxation physics to create authentic fluid-like responses.

This component handles complex shader mathematics automatically. Grid coordinate mapping, mouse velocity calculations, distance-based influence, and exponential decay all work together seamlessly. The result feels like touching actual liquid through your screen.

Features

Three.js shader rendering with custom fragment shaders for real-time grid displacement
Mouse-responsive distortion with velocity-based influence and distance calculations
Grid-based displacement using data textures for precise per-vertex control
Relaxation physics with exponential decay for natural energy dissipation
Image aspect preservation with automatic scaling and orthographic projection
Performance optimization with efficient WebGL context management and cleanup
Responsive design with ResizeObserver support for dynamic container sizing
Touch support with mouse leave handling and state reset functionality
Customizable parameters for grid density, mouse sensitivity, and distortion strength
Memory management with proper texture disposal and resource cleanup

API Reference

GridDistortion

Prop	Type	Default	Description
`imageSrc`	`string`	-	Required - URL or path to image source
`grid`	`number`	`15`	Grid density (higher = more detail)
`mouse`	`number`	`0.1`	Mouse influence radius (0-1)
`strength`	`number`	`0.15`	Distortion intensity multiplier
`relaxation`	`number`	`0.9`	Energy decay rate (0-1)
`className`	`string`	-	Additional CSS classes
`...props`	`HTMLAttributes<HTMLDivElement>`	-	All standard div props

Grid Density Settings

Different grid values for various detail levels:

Grid	Detail	Performance	Use Case
10	Low	High	Simple effects, mobile
15	Medium	Good	Balanced quality/performance
25	High	Medium	Desktop, detailed distortion
40	Very High	Low	High-end devices only

Distortion Parameters

Different parameter combinations for various effects:

Effect	Mouse	Strength	Relaxation	Description
Subtle	0.05	0.1	0.95	Gentle ripples
Standard	0.1	0.15	0.9	Balanced interaction
Dramatic	0.2	0.3	0.85	Strong distortions
Fluid	0.15	0.25	0.92	Liquid-like behavior

Shader mathematics

Grid Displacement: Uses data textures to store per-vertex displacement vectors, enabling precise control over individual grid points with real-time updates.

Mouse Influence: Calculates distance-based influence with inverse square falloff, ensuring realistic force distribution around cursor position.

Velocity Integration: Tracks mouse velocity to determine distortion direction and magnitude, creating natural push/pull effects based on movement speed.

Relaxation Physics: Implements exponential decay with configurable relaxation factor, allowing energy to dissipate naturally over time like real fluid dynamics.

Performance considerations

Grid Resolution Impact: Higher grid values create more detailed distortion but increase computational cost quadratically. Balance detail with performance requirements.

Shader Optimization: Uses efficient WebGL rendering with minimal texture updates and optimized fragment shader calculations for consistent 60fps performance.

Memory Management: Properly disposes of Three.js resources including geometries, materials, textures, and WebGL contexts to prevent memory leaks.

ResizeObserver: Uses ResizeObserver when available for efficient resize handling, falling back to window resize events for better performance.

Common gotchas

Image Loading: Component requires successful image loading before distortion works. Ensure image URLs are accessible and use appropriate CORS headers for cross-origin images.

Grid Size Limits: Very high grid values (>50) can cause performance issues on lower-end devices. Test across different hardware capabilities.

Container Sizing: Component fills its container completely. Ensure parent element has defined dimensions for proper distortion calculation and rendering.

Mouse Coordinates: Uses normalized coordinates for consistent behavior across different container sizes and device pixel ratios.

WebGL Context: Requires WebGL-enabled browser. Component will fail silently if WebGL is not available or context creation fails.

Relaxation Range: Relaxation values outside 0.8-0.99 range may cause unstable behavior. Values too low prevent settling, values too high create sluggish response.

React Grid Distortion Background

Mouse-responsive image warping with grid displacement

Installation

Why static images feel lifeless

Features

API Reference

GridDistortion

Grid Density Settings

Distortion Parameters

Shader mathematics

Performance considerations

Common gotchas

You might also like

Liquid Chrome Background

Grid Motion Background

Plasma Background

Orb

Questions developers actually ask

On this page

React Grid Distortion Background