Join our Discord Community

React Ballpit Background

React ballpit background with Three.js physics simulation. Features realistic sphere collisions, mouse-controlled gravity, and customizable materials for interactive physics experiences.

Building physics simulations?

Join our Discord community for help from other developers working with Three.js physics and interactive 3D experiences.


Ever wanted to create that satisfying physics simulation where spheres bounce, collide, and respond to your cursor like a digital ball pit? Those mesmerizing interactions where each sphere has weight, momentum, and realistic collision responses that make you want to keep moving your mouse just to watch the physics unfold? The way lighting follows the action and materials catch reflections like real metallic spheres? Most physics animations rely on simple tweening or CSS transforms, but they lack the authentic physical behavior that comes from proper collision detection and momentum conservation.

This React component creates that captivating ballpit effect using Three.js with full physics simulation, featuring realistic sphere collisions, mouse-controlled gravity wells, and physically-based materials that respond naturally to light and environment.

Interactive physics with realistic sphere collisions

Watch spheres bounce, collide, and follow your cursor with authentic physics behavior:

Loading component...

Built for React applications with TypeScript and optimized Three.js rendering. Uses custom physics engine with sphere-to-sphere collision detection while providing intuitive controls for gravity, friction, and material properties. Perfect for interactive backgrounds, physics demonstrations, or any application needing satisfying tactile feedback.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/ballpit.json
npx shadcn@latest add https://www.shadcn.io/registry/ballpit.json
pnpm dlx shadcn@latest add https://www.shadcn.io/registry/ballpit.json
bunx shadcn@latest add https://www.shadcn.io/registry/ballpit.json

Why fake physics feels wrong

Developers create bouncing animations with CSS easing functions and consider them realistic. Maybe they add some basic gravity with linear acceleration. The problem? Fake physics animations can't capture the organic, interconnected nature of real physical systems where every action creates authentic reactions.

Proper physics simulations with Three.js change everything. They tap into our fascination with cause and effect—the way spheres transfer momentum during collisions, how gravity creates natural clustering, the satisfying unpredictability that emerges from simple rules. The mathematics use real physics equations for acceleration, collision response, and energy conservation.

This component handles complex physics calculations automatically. Collision detection algorithms, momentum transfer, boundary conditions, and material lighting all work together seamlessly. The result feels like playing with actual physical objects through your screen.

Features

  • Three.js physics engine with custom sphere collision detection and momentum transfer
  • Mouse-controlled gravity with raycasting for precise 3D cursor tracking
  • Realistic material rendering using physically-based materials with environment mapping
  • Sphere-to-sphere collisions with proper overlap resolution and velocity transfer
  • Boundary physics with configurable wall bounce and energy conservation
  • Subsurface scattering with custom shader modification for organic lighting effects
  • Dynamic lighting with point lights that follow the lead sphere position
  • Color gradients supporting smooth interpolation across sphere instances
  • Performance optimization with efficient collision algorithms and instanced rendering
  • Touch support with full mobile interaction including multi-touch prevention

API Reference

Ballpit

PropTypeDefaultDescription
followCursorbooleantrueEnable mouse cursor following behavior
countnumber200Total number of spheres in simulation
colorsnumber[][0, 0, 0]Array of hex colors for sphere gradient
gravitynumber0.5Gravitational acceleration strength
frictionnumber0.9975Air friction coefficient (0-1)
minSizenumber0.5Minimum sphere radius
maxSizenumber1Maximum sphere radius
classNamestring-Additional CSS classes
...propsHTMLAttributes<HTMLDivElement>-All standard div props

Physics Parameters

Different physics settings for various behaviors:

SettingGravityFrictionEffect
Floating00.999Zero gravity, slow decay
Realistic0.50.9975Earth-like physics
Heavy1.00.995Strong gravity, quick settling
Bouncy0.30.999Light gravity, high energy

Color Schemes

Different color combinations for various aesthetics:

ThemeColorsHex Values
NeonPurple-Pink-Blue[0x6366f1, 0x8b5cf6, 0xec4899]
OceanBlue-Teal-Green[0x0ea5e9, 0x06b6d4, 0x10b981]
SunsetOrange-Pink-Red[0xf97316, 0xf59e0b, 0xef4444]
MonochromeGray Scale[0x374151, 0x6b7280, 0x9ca3af]

Physics mathematics

Collision Detection: Uses sphere-to-sphere distance calculations with radius summation to detect overlaps, followed by separation and momentum transfer algorithms.

Momentum Conservation: Implements elastic collision response with velocity exchange based on sphere masses and collision angles for realistic physics behavior.

Boundary Conditions: Handles wall collisions with configurable bounce coefficients and proper velocity reflection to maintain energy within the system.

Gravity Wells: Uses 3D raycasting to project mouse coordinates onto the physics plane, creating attractive force centers that spheres naturally gravitate toward.

Performance considerations

Instanced Rendering: Uses Three.js InstancedMesh for efficient rendering of multiple identical sphere geometries with individual transforms and colors.

Collision Optimization: Implements spatial partitioning considerations and early exit strategies to reduce O(n²) collision checks for large sphere counts.

WebGL Context Management: Properly handles WebGL context creation and cleanup with intersection observers for performance and memory efficiency.

Animation Loop: Uses requestAnimationFrame with delta time calculations for consistent physics updates regardless of frame rate variations.

Common gotchas

Sphere Count Impact: Higher sphere counts increase collision calculations exponentially. Consider reducing count on lower-end devices for consistent performance.

Color Array Length: Component expects hex color values as numbers, not strings. Use 0x prefix for hex colors like 0xff0000 for red.

Physics Stability: Very high friction values near 1.0 can cause physics instability. Keep friction between 0.99 and 0.999 for stable behavior.

Container Sizing: Component fills its container completely. Ensure parent element has defined dimensions for proper physics boundary calculations.

Mouse Coordinates: Uses normalized device coordinates for 3D mouse tracking. Component handles coordinate system conversion automatically.

Mobile Performance: Physics simulations are computationally expensive on mobile. Consider reducing sphere count and simplifying materials for mobile devices.

You might also like

Questions developers actually ask