OrbitGallery — 3D Carousel for React & Three.js (WebGL)

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.