Perspective Cards: a 3D parallax gallery hero with no renders on pointer move, and five traps
How Perspective Cards floats image cards in 3D around a headline with Motion values, and five traps: React Compiler lint, flex min-width, mobile LCP, Playwright clicks and bundle sizes.
Ramin ValadanProved GitHub account and website, confirmed e-mail: checked by UpFork·5 min read·
A 3D parallax image gallery hero for React: cards float around your headline, follow the cursor like a camera, lift and face you on hover, and open into a cinematic lightbox. Framer Motion, light/dark themes, keyboard, touch and reduced-motion support.
Perspective Cards turns a collection into a scene. Ten image cards float in 3D around the headline, all sharing one vanishing point and each turned toward it, and the whole scene moves with the cursor like a camera: near cards travel more than far ones, while the headline drifts gently the other way. Hover a card and it lifts and turns to face you; click it and that exact card grows into a lightbox with swipe, thumbnails and a focus trap, then flies back into its place when you close it. Three layouts (orbit, scatter, arc) are placed by a seeded engine that never lets a card cover the headline or another card's caption; tablets get a two-row arc, and phones a fan of cards and a swipeable strip.
This article is for anyone, person or AI, building a pointer-driven 3D scene in React: how it moves with no React render, and five traps we hit, each with its fix.
A scene in Motion values
Everything that moves lives in Motion values, created once per scene and once per card, and the cards' transforms are computed from them. A pointer move sets a few values and the browser composites the result: a Chrome trace of the pointer sweeping the stage shows zero React commits. Even the glare is a pre-drawn highlight moved by transform, so following the pointer never repaints:
Phones: a strip of cards
Testing and measuring
Checked
29 unit tests; ESLint with the React Compiler rules and TypeScript clean; axe finds no violations in light, dark and with the lightbox open. Lighthouse desktop 98–99 for Performance and 100 for the rest. A Chrome trace of the pointer sweeping the stage shows no layout, no paint and no React commits. No horizontal overflow from 320 to 1920 px wide. On UpFork it passed the importer and the preview builder with all three demos.
Make it yours
<PerspectiveCards /> takes your items (each with src, alt, title, width and height, and optionally a description and an href), the headline, subheadline, eyebrow and cta, and a layout of orbit, scatter or arc with a seed. depth, parallax, tilt and float tune the motion, theme and accent the look, lightbox and onCardClick what a click does, and renderImage lets you draw the pictures with your own image component. The component's README has the full table and a tuning guide.
How Velvet Sidebar keeps its frosted glass clean and its first fold smooth, and five traps: blend modes over backdrop-filter, layer promotion, WebGL in React's dev effects, GLSL and lint.
Ramin ValadanProved GitHub account and website, confirmed e-mail: checked by UpFork·4 min read··AI
5 lessons
Behind the build
Behind the build · Duet Sidebar — Glassmorphism Icon Dock & Expandable Menu for React
How Duet Sidebar's dock and menu share state without React renders, and five traps: light-dark() with numbers, self-hosted demo fonts, compiler lint, dev double effects and exiting views.
Ramin ValadanProved GitHub account and website, confirmed e-mail: checked by UpFork·5 min read··AI
5 lessons
Behind the build
Behind the build · Commander — Pet Shop Hero Section with Cursor-Tracking Cat (React + Next.js)
How Commander scrubs 90 video frames on a canvas so a cat follows the pointer, and eight traps: pill borders, a canvas benchmark, a spotlight, focus rings and a hero that broke in a preview.
Ramin ValadanProved GitHub account and website, confirmed e-mail: checked by UpFork·7 min read··AI
8 lessons1
the React Compiler's lint rules reject mutating an object that is held in state, so every one of those assignments was an error.
The fix
the scene is a set of Motion values made once (useState(createScene)), and the layout effect calls .set() on them. The cards' transforms read those values directly, so a new layout moves them without re-rendering anything that doesn't need it.
Evidence
rig.ts lines 36–48; PerspectiveCards.tsx lines 225–229; the lint run in the build notes.
The fix
min-width: 0 on the strip item, so the basis wins and the description is cut off with its ellipsis instead.
Evidence
styles.css lines 624–626; the phone screenshots and card measurements in the build notes.
The fix
the fan's cards are sized below the headline block (min(44cqw, 210px)), so the headline, which is in the first HTML, is the largest paint. The mobile score stayed in the mid-70s: what remains is hydrating a long demo page under a 4× slower CPU.
Evidence
styles.css lines 576–580; the Lighthouse runs in the build notes.
The fix
click the card by its position (its bounding box's centre, with page.mouse.click). click({ force: true }) also skips the stability check.
Evidence
the accessibility test's output in the build notes.
The fix
the first-paint size is the stage's chunk plus everything it imports statically (import-statement edges, followed recursively); each lazy part is counted as its own closure minus what the stage already brought. The result: 11.8 kB gzipped for the stage, 4.0 kB for the lightbox (fetched before the first click) and 2.0 kB for the deck (phones only).
Evidence
scripts/size.mjs in the repo.
/** A chunk plus everything it imports statically: what has to arrive before it runs. */const closure = (k, seen = new Set()) => { if (seen.has(k)) return seen; seen.add(k); for (const i of outputs[k].imports) if (i.kind === "import-statement" && outputs[i.path]) closure(i.path, seen); return seen;};const entryOf = (name) => Object.keys(outputs).find((k) => outputs[k].entryPoint?.endsWith(name));const stage = closure(entryOf("PerspectiveCards.tsx"));
/* Glare: a pre-drawn highlight moved by transform, so following the pointer never repaints. */.pc-glare { position: absolute; left: 0; top: 0; border-radius: 50%; pointer-events: none; opacity: 0; mix-blend-mode: overlay;
.pc-fan-card { position: absolute; /* Smaller than the headline block, so the headline stays the page's largest paint (LCP). */ width: min(44cqw, 210px); max-height: 94%;
Comments
0 comments
No comments yet. Questions, what you built with it, what could be better: its developer reads them.
Sign in to comment.
Sign in to comment