Project cards on a curved arc above a reflective floor. Drag, scroll or use the arrow keys to turn it; click the
front card and it flies to fill the screen while the project opens over it. A sellable React component with a
headless core, three layouts, light, dark and auto themes, an accessible and indexable list, and a CSS fallback when
there is no WebGL.
What's here
package/ the component: source, tests, build (tsup: ESM + CJS + .d.ts), README with every prop and recipe
src/ OrbitGallery, the scene (cards, floor, camera rig, effects), the headless store and hooks,
the layouts, the HTML layer (overlay, cursor, detail view, accessible list), the CSS fallback
test/ vitest: layout geometry, seamless wrap, snapping, the state machine, the hook
demo/ the landing page (Vite, prerendered to static HTML) with a leva panel and "Copy props"
src/data/ the twelve demo projects (items.ts) and their blur-up placeholders
public/media/ their covers (WebP) and the two loops (MP4)
art/ the covers and loops are drawn in code: art.html holds the shaders, render.mjs renders them
e2e/ the Playwright smoke test
screenshots/ the screenshots above, made by scripts/screenshots.mjs
registry/ the component as flat files for UpFork's live preview and the shadcn CLI (scripts/registry.mjs)
PLAN.md the plan written before the code, and where the build departs from the brief
LISTING.md what goes into UpFork's product form
The component's documentation is package/README.md.
Run it
Node.js 22 and pnpm.
pnpm install
pnpm dev # the demo with live reload, http://localhost:4101
pnpm build # the library (package/dist) and the prerendered demo (demo/dist)
pnpm preview # the built demo, http://localhost:4100
pnpm test # 46 unit tests
pnpm e2e # the Playwright smoke test (builds and serves the demo itself; uses the installed Chrome)
pnpm lint
pnpm typecheck
pnpm --filter orbit-gallery size prints the library's gzipped size after a build (about 39 KB; the budget is 60).
The demo reads a few settings from the address bar, handy for links and screenshots:
/?layout=grid&theme=light&effects=cinematic#full.
Make it yours
- Projects:
demo/src/data/items.ts. Each item needs an id, a title and an image; a subtitle,
description, tags, href, video, accent and a 24 px placeholder are optional. The demo's are fictional.
- Corners: the
brand, nav and cta props take any markup (see demo/src/App.tsx).
- Look: the
theme prop (eight tokens: colours and the two fonts), radius, curvature, gap, cardAspect,
floor and effects. Open Tune on the demo, set it up by eye, then Copy props.
- Cover art:
demo/art/art.html draws each demo picture in a fragment shader. node art/render.mjs preview <dir>
renders previews, stills <dir> the 4096 × 2560 originals, frames <dir> <name> <seconds> <fps> a seamless loop;
python art/build-media.py <stills> [<framesRoot>] writes the WebP covers, the placeholders and the MP4s.
Checks
Verified in Chrome (Windows, Intel Iris Plus) on the production build:
- Lighthouse, desktop: Performance 91–92, Accessibility 100, Best practices 100, SEO 100 (LCP 0.4 s, CLS 0.001).
- No console errors or warnings (three is pinned to 0.182: three r183+ makes React Three Fiber 9 warn about
THREE.Clock).
- Twenty open/close cycles: geometries, textures and programs stay flat, the JS heap stays at 10 MB.
- A Next.js 16 App Router app builds and runs with it both through
next/dynamic and as a plain server-rendered
import.
- Without WebGL (
--disable-gpu), the CSS fallback renders and responds to the keys.
Licence
Sold on UpFork under the UpFork Standard License: see package/LICENSE.md.