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:
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
Prop | Type | Default | Description |
---|---|---|---|
followCursor | boolean | true | Enable mouse cursor following behavior |
count | number | 200 | Total number of spheres in simulation |
colors | number[] | [0, 0, 0] | Array of hex colors for sphere gradient |
gravity | number | 0.5 | Gravitational acceleration strength |
friction | number | 0.9975 | Air friction coefficient (0-1) |
minSize | number | 0.5 | Minimum sphere radius |
maxSize | number | 1 | Maximum sphere radius |
className | string | - | Additional CSS classes |
...props | HTMLAttributes<HTMLDivElement> | - | All standard div props |
Physics Parameters
Different physics settings for various behaviors:
Setting | Gravity | Friction | Effect |
---|---|---|---|
Floating | 0 | 0.999 | Zero gravity, slow decay |
Realistic | 0.5 | 0.9975 | Earth-like physics |
Heavy | 1.0 | 0.995 | Strong gravity, quick settling |
Bouncy | 0.3 | 0.999 | Light gravity, high energy |
Color Schemes
Different color combinations for various aesthetics:
Theme | Colors | Hex Values |
---|---|---|
Neon | Purple-Pink-Blue | [0x6366f1, 0x8b5cf6, 0xec4899] |
Ocean | Blue-Teal-Green | [0x0ea5e9, 0x06b6d4, 0x10b981] |
Sunset | Orange-Pink-Red | [0xf97316, 0xf59e0b, 0xef4444] |
Monochrome | Gray 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
Particles
Interactive particle systems with physics
Orb
Dynamic orb with organic noise morphing
Liquid Chrome Background
Metallic liquid effects with WebGL rendering
Grid Motion Background
Interactive grid animations with mouse parallax
Questions developers actually ask
React Balatro Background
React Balatro-style background with WebGL rendering. Features swirling psychedelic patterns, mouse interaction, and customizable colors inspired by the card game aesthetic.
Exploding Beams Background
React background with energy beams that explode on collision. Interactive particle effects using Framer Motion, TypeScript, and shadcn/ui.