React Grid Motion Background

Powered by

React

GSAP

Ever watched a grid of elements dance and flow in response to your mouse movement, creating that mesmerizing parallax effect that makes interfaces feel alive and responsive? The way each row moves with different speeds and directions, creating depth and dimension that transforms flat layouts into dynamic, three-dimensional experiences? Most grid layouts are static, predictable, and lack the organic responsiveness that makes user interactions feel magical. This React component creates that captivating grid motion effect with GSAP animations, customizable content, and smooth inertia-based movement that responds naturally to mouse input.

Interactive grid with mouse-responsive parallax

Watch grid elements flow with alternating directional movement and smooth inertia effects:

import GridMotionBackground from "@/components/ui/shadcn-io/grid-motion-background"export default function GridMotionBackgroundDemo() {  return (    <div className="relative w-full h-full bg-black rounded-lg overflow-hidden">      <GridMotionBackground         items={[          "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1518837695005-2083093ee35b?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=300&h=300&fit=crop&sat=-100",          "https://images.unsplash.com/photo-1418065460487-3956ef847988?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1483728642387-6c3bdd6c93e5?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=300&h=300&fit=crop&hue=60",          "https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=300&h=300&fit=crop&sat=2",          "https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=300&h=300&fit=crop&hue=180",          "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=300&h=300&fit=crop",          "https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=300&h=300&fit=crop&hue=120",          "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=300&h=300&fit=crop&sepia=80",          "https://images.unsplash.com/photo-1418065460487-3956ef847988?w=300&h=300&fit=crop&sat=-50",          "https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=300&h=300&fit=crop&blur=1",          "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=300&h=300&fit=crop&hue=240",          "https://images.unsplash.com/photo-1483728642387-6c3bdd6c93e5?w=300&h=300&fit=crop&sat=2",          "https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=300&h=300&fit=crop&hue=300",          "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=300&h=300&fit=crop&contrast=2",          "https://images.unsplash.com/photo-1418065460487-3956ef847988?w=300&h=300&fit=crop&hue=90",          "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=300&h=300&fit=crop&sat=2",          "https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=300&h=300&fit=crop&hue=45",          "https://images.unsplash.com/photo-1483728642387-6c3bdd6c93e5?w=300&h=300&fit=crop&hue=200"        ]}        gradientColor="#EC4899"        maxMoveAmount={280}        baseDuration={0.7}        gridRows={4}        gridCols={7}        rotation={-18}      />    </div>  )}

// @ts-nocheck'use client';import React, { useEffect, useRef, forwardRef } from "react";import { gsap } from "gsap";import { cn } from '@/lib/utils';export interface GridMotionBackgroundProps extends React.HTMLAttributes<HTMLDivElement> {  items?: string[];  gradientColor?: string;  maxMoveAmount?: number;  baseDuration?: number;  gridRows?: number;  gridCols?: number;  rotation?: number;}export const GridMotionBackground = forwardRef<HTMLDivElement, GridMotionBackgroundProps>(({  className,  items = [],  gradientColor = "black",  maxMoveAmount = 300,  baseDuration = 0.8,  gridRows = 4,  gridCols = 7,  rotation = -15,  ...props}, ref) => {  // props already contains only DOM props after destructuring above  const domProps = props;  const gridRef = useRef<HTMLDivElement>(null);  const rowRefs = useRef<(HTMLDivElement | null)[]>([]);  const mouseXRef = useRef<number>(0);  const totalItems = gridRows * gridCols;  const defaultItems = Array.from(    { length: totalItems },    (_, index) => `Item ${index + 1}`  );  const combinedItems =    items.length > 0 ? items.slice(0, totalItems) : defaultItems;  useEffect(() => {    // Initialize mouse position    mouseXRef.current = typeof window !== 'undefined' ? window.innerWidth / 2 : 0;    if (typeof window === 'undefined') return;    gsap.ticker.lagSmoothing(0);    const handleMouseMove = (e: MouseEvent): void => {      mouseXRef.current = e.clientX;    };    const updateMotion = (): void => {      const inertiaFactors = [0.6, 0.4, 0.3, 0.2];      rowRefs.current.forEach((row, index) => {        if (row) {          const direction = index % 2 === 0 ? 1 : -1;          const moveAmount =            ((mouseXRef.current / window.innerWidth) * maxMoveAmount -              maxMoveAmount / 2) *            direction;          gsap.to(row, {            x: moveAmount,            duration:              baseDuration + inertiaFactors[index % inertiaFactors.length],            ease: "power3.out",            overwrite: "auto",          });        }      });    };    const removeAnimationLoop = gsap.ticker.add(updateMotion);    window.addEventListener("mousemove", handleMouseMove);    return () => {      window.removeEventListener("mousemove", handleMouseMove);      removeAnimationLoop();    };  }, [maxMoveAmount, baseDuration]);  return (    <div      ref={(node) => {        gridRef.current = node;        if (typeof ref === 'function') ref(node);        else if (ref) ref.current = node;      }}      className={cn("h-full w-full overflow-hidden", className)}      {...domProps}    >      <section        className="w-full h-screen overflow-hidden relative flex items-center justify-center"        style={{          background: `radial-gradient(circle, ${gradientColor} 0%, transparent 100%)`,        }}      >        <div className="absolute inset-0 pointer-events-none z-[4] bg-[length:250px]"></div>        <div           className="gap-4 flex-none relative w-[150vw] h-[150vh] grid grid-cols-1 origin-center z-[2]"          style={{             gridTemplateRows: `repeat(${gridRows}, 1fr)`,            transform: `rotate(${rotation}deg)`          }}        >          {Array.from({ length: gridRows }, (_, rowIndex) => (            <div              key={rowIndex}              className="grid gap-4"              style={{                 willChange: "transform, filter",                gridTemplateColumns: `repeat(${gridCols}, 1fr)`              }}              ref={(el) => {                if (el) rowRefs.current[rowIndex] = el;              }}            >              {Array.from({ length: gridCols }, (_, itemIndex) => {                const content = combinedItems[rowIndex * gridCols + itemIndex];                return (                  <div key={itemIndex} className="relative">                    <div className="relative w-full h-full overflow-hidden rounded-[10px] bg-[#111] flex items-center justify-center text-white text-[1.5rem] aspect-square">                      {typeof content === "string" &&                      content.startsWith("http") ? (                        <div                          className="w-full h-full bg-cover bg-center absolute top-0 left-0"                          style={{ backgroundImage: `url(${content})` }}                        />                      ) : (                        <div className="p-4 text-center z-[1] text-xs sm:text-sm md:text-base break-all">                          {content}                        </div>                      )}                    </div>                  </div>                );              })}            </div>          ))}        </div>        <div className="relative w-full h-full top-0 left-0 pointer-events-none"></div>      </section>    </div>  );});GridMotionBackground.displayName = 'GridMotionBackground';export default GridMotionBackground;

Built for React applications with TypeScript and Next.js. Uses GSAP for high-performance animations with hardware acceleration and optimized ticker system. Mathematical inertia calculations create natural movement patterns while customizable grid layouts support any content type. Perfect for hero sections, portfolio showcases, or any interface needing sophisticated interactive backgrounds.

Installation

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

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

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

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

Why static grids feel lifeless

Developers create CSS grids with hover effects and consider them interactive. Maybe they add a simple transform that scales on hover. The problem? Static layouts can't capture the organic, responsive nature of truly interactive designs that make users want to explore and engage.

Grid motion backgrounds with GSAP physics change everything. They tap into our fascination with parallax and depth—the way objects at different distances move at different speeds, how layers create the illusion of three-dimensional space. The animation calculations use mathematical inertia and easing functions to generate natural, physics-based movement.

This component handles complex animation mathematics automatically. GSAP ticker optimization, inertia calculations, alternating directional flow, and smooth easing curves all work together seamlessly. The result feels like controlling a living, breathing grid that responds to your every movement.

Features

• GSAP-powered animations with hardware acceleration and optimized ticker system
• Mouse-responsive parallax with real-time coordinate tracking and smooth interpolation
• Alternating row directions creating natural parallax depth and visual rhythm
• Customizable grid layout supporting any number of rows and columns
• Content flexibility supporting text, emojis, images, or custom React elements
• Inertia-based movement with mathematical easing for natural, physics-based motion
• Gradient backgrounds with customizable radial gradient overlays
• Rotation controls for angled grid presentations and dynamic compositions
• Performance optimization with GSAP lag smoothing and efficient rendering
• TypeScript support with complete prop forwarding and type safety

API Reference

GridMotionBackground

Grid Configurations

Different grid layouts for various use cases:

Content Types

The component supports various content formats:

Animation mathematics

Inertia Calculation: Uses alternating direction multipliers with mathematical easing curves to create natural parallax movement that varies by row for depth illusion.

Mouse Tracking: Normalizes mouse coordinates to 0-1 range, then applies movement calculations with configurable maximum displacement for consistent behavior across screen sizes.

GSAP Ticker Optimization: Utilizes GSAP's optimized ticker system with lag smoothing disabled for consistent 60fps performance and smooth animation updates.

Easing Functions: Implements "power3.out" easing curves for natural deceleration that mimics real-world physics and creates satisfying motion feel.

Performance considerations

GSAP Ticker: Uses GSAP's optimized ticker instead of requestAnimationFrame for better performance and consistency across devices.

Lag Smoothing: Disables GSAP lag smoothing to prevent animation jumps during performance drops, maintaining smooth visual experience.

Transform Optimization: Uses CSS transforms exclusively for movement, enabling hardware acceleration and GPU rendering for smooth animations.

Grid Size Impact: Larger grids (more rows/columns) require more DOM elements and animation calculations. Consider reducing grid size on mobile devices.

Common gotchas

Item Array Length: If fewer items than grid slots are provided, remaining slots show default "Item N" text. Ensure your items array matches the grid size.

Image URL Detection: Component detects image URLs by checking if string starts with "http". Local images need full URLs or different handling.

Mouse Coordinate System: Uses clientX coordinates which may behave differently across browsers. The component normalizes these for consistent behavior.

GSAP Dependencies: Requires GSAP library to be installed. Component will fail silently if GSAP is not available in the bundle.

Rotation Boundaries: Extreme rotation values (greater than 45 degrees) may cause grid elements to move outside viewport boundaries.

Animation Overwrite: Uses GSAP's "auto" overwrite mode to prevent animation conflicts when mouse moves rapidly.

You might also like

Questions developers actually ask