CustomBounce Ball — Free GSAP Squash & Stretch Snippet

GSAP's built-in bounce.out moves a value like a bouncing ball — but a *real* ball also squashes on impact and stretches in flight, Disney's most famous animation principle. Faking that by hand means computing exactly when each bounce contacts the floor and syncing scale keyframes to those instants. CustomBounce (free on the CDN since 3.13) does the sync for you: one call generates a position ease *and* a matched squash ease whose deformations land precisely on every floor contact.

One create() call, two synchronized eases

CustomBounce.create('ball', { strength: 0.6, squash: 3 }) registers two named eases: 'ball', the bounce trajectory for y, and 'ball-squash', a companion curve that spikes exactly at the trajectory's contact points. Two separate tweens — one moving y, one animating scaleX/scaleY — run over the *same duration* with their respective eases, and because both curves were generated from the same bounce math, deformation and impact can never drift apart. That co-generation is the entire plugin; hand-synced versions break the moment you retune the bounce.

strength is restitution

The strength parameter (0–1) is effectively the coefficient of restitution: how much energy survives each bounce. Soft (0.3) dies in a couple of low rebounds; Superball (0.8) keeps rebounding tall and long. The demo scales total duration with strength (1.6 + strength) because bouncier balls genuinely take longer to settle — a fixed duration would compress the superball's extra bounces into frantic jitter.

squash: 3 and the transform origin

squash sets how much of the ease's time is spent deformed relative to airborne travel. The squash tween drives scaleX: 1.5, scaleY: 0.55 — wider and flatter — with transformOrigin: '50% 100%' so the ball flattens *against the floor* rather than around its own center (center-origin squash makes the ball appear to levitate mid-impact, the most common squash-and-stretch mistake).

The shadow rides the same position ease

The contact shadow grows and darkens using the *same* 'ball' ease on scale and opacity — so it inflates as the ball approaches and shrinks as it rebounds, in perfect sync, with zero additional timing logic. Reusing a registered ease across properties is the quiet superpower of named CustomEases.

Replays are kill-set-play

Each button re-creates the ease with a new strength (re-registering under the same name replaces it), kills running tweens, resets transforms, and replays — the standard idiom for parameterized animations, keeping every run interrupt-safe.

Where CustomBounce sits in the ease family

It's built on CustomEase (SVG-path-defined easing curves — also loaded here as a dependency) alongside CustomWiggle. Bounce trajectories are painful to draw by hand as paths; CustomBounce is essentially a curve *generator* for the physics-shaped subset. For arbitrary hand-drawn feels, drop to raw CustomEase; for oscillation, see custom wiggle icons.

Customizing it

Tweak squash (1 subtle, 4 cartoon), drop from a click position, or apply the paired-eases idea to UI: a dropping modal or badge with landing squash reads delightfully physical. Related motion: ease shopping in gsap ease gallery, simulated momentum in physics props pucks, gravity arcs in physics 2d burst, and the CSS-keyframe breathing animation.