Gravity Stack

Any real component, dropped into a matter-js world, they fall, collide and pile up, tap one to blast it.

Reanimatedmatter-jsHapticsSource

Prerequisites

Gravity Stack needs a real 2D physics engine for the falling and colliding, plus haptics for the blast.


npx expo install matter-js expo-haptics react-native-reanimated

Install


npx @rslab/cli add gravity-stack

Usage

import { useRef } from 'react';

import { GravityStack, type GravityItem, type GravityStackHandle } from '@/components/ui/GravityStack';

import { Tag } from '@/components/ui/Tag';

import { Button } from '@/components/ui/Button';

const ref = useRef<GravityStackHandle>(null);

const items: GravityItem[] = ['Music', 'Coffee', 'Design'].map((label, i) => ({
  content: (
    <Pressable onPress={() => ref.current?.explodeAt(i)}>
      <Tag label={label} />
    </Pressable>
  ),
}));

<GravityStack ref={ref} items={items} height={340} />

<Button onPress={() => ref.current?.shake()}>Shake the pile</Button>;

items accepts any rendered content, a Tag, a Button, an Avatar, whatever should fall and pile up. Wrap each one in a Pressable calling explodeAt(index) to blast it on tap, GravityStack's own wrapper never intercepts touches so the inner content still gets them normally.

Props

PropTypeDefault

items

{ content: ReactNode }[]

-

The set of components to drop in. Treated as fixed for the component's lifetime, changing its length rebuilds the whole physics world.

height?

number

320

Container height in px.

gravity?

number

1

Downward acceleration passed straight to matter-js. Higher falls faster and lands harder.

className?

string

-

Extend or override the container.

Handle (via ref)

shake(): jolts every settled item with a random upward and angular impulse, so the pile bounces and resettles
explodeAt(index): a localized blast centered on items[index]'s current position, pushing it and anything nearby outward

How it works

matter-js drives the simulation, Reanimated drives the pixels. matter-js is a pure JS physics engine, it isn't worklet-compatible, so it steps on the JS thread inside a requestAnimationFrame loop. Every tick, each body's position and angle are copied straight into that item's shared values, which is enough to drive the actual transform on the UI thread without any React re-render.
Items are measured before they're dropped. Every item renders once, invisibly, off-screen purely to read its real width and height, matter-js needs accurate dimensions to build a collision body that actually matches what's on screen.
Bodies are chamfered rectangles, not boxes. Each body's corner radius is set to half its height, so the invisible collision shape is a pill matching a Tag's or Button's real rounded shape, items nudge past each other's actual edges instead of their bounding boxes.
Falls are staggered, not simultaneous. Every body spawns above the container at a different height, so items drop in one after another and land on whatever's already piled up, instead of all free-falling in lockstep.
The physics wrapper never intercepts touches. Whatever real component sits inside, a Button, say, still gets its own taps, its own press animation, and its own haptic completely unmodified.
explodeAt falls off by distance. Every body within range of the tapped item gets pushed directly away from it, scaled by how close it is. The tapped item itself is zero distance from its own epicenter, so it gets a full-strength kick in a random direction instead.

Tuning

RESTITUTION / FRICTION / FRICTION_AIR: raise RESTITUTION for a bouncier landing, lower the other two to let items slide further before settling
EXPLOSION_RADIUS / EXPLOSION_SPEED: how far a blast reaches and how hard it hits at the epicenter
the spawn stagger in the body-creation loop: how spaced out each item's drop is before the next one starts falling

See exactly how this works with an RSLAB subscription.

Get Pro

Gravity Stack

Prerequisites

Install

Usage

Props

On this page