Explore ThreeUI: Open-Source Catalog of Live Interactive 3D Components for the Community

Introduction to ThreeUI: Vision, Scope, and Position in the 3D Web Landscape

ThreeUI is an open‑source catalog of ready‑made 3D UI widgets built on top of Three.js. The repo lives on GitHub under an MIT license, so anyone can clone, fork, or submit a component. Every entry ships with a live demo that runs in the browser, letting you test interaction without writing a single line of code.

The library targets developers who need UI in WebGL scenes – game makers, VR/AR creators, and data‑visualization engineers. It extends the core Three.js objects with higher‑level primitives like buttons, sliders, and panels. Those primitives are reusable, configurable, and work with the standard Three.js render loop.

Deep Dive Architecture

ThreeUI wraps Three.js Meshes with a thin controller layer that maps pointer events to UI state. The controller uses Raycaster under the hood, so it respects the same camera and scene hierarchy you already have.

The catalog follows a semantic versioning scheme. Minor releases add new components, while major bumps may introduce breaking API changes. The changelog is auto‑generated from GitHub releases, making upgrades predictable.

Real-World Engineering Examples

• A product configurator for a furniture retailer used ThreeUI's Slider and ColorPicker to let shoppers tweak dimensions and finishes in real time.
• An educational VR app layered ThreeUI's Panel and Button on top of a Three.js skybox, giving users a familiar UI without breaking immersion.

Core Architecture: Integration with Three.js r152 and React 18 via React‑Three‑Fiber

ThreeUI sits on top of the proven stack of Three.js r152, React 18, and React‑Three‑Fiber. The three pieces talk to each other through a thin wrapper that turns Three.js objects into React components.

When the app starts, @react-three/fiber creates a WebGLRenderer, a scene, and a camera. From there, every <ThreeUI.*> element you write becomes a Fiber node that the reconciler maps to a native Three.js object.

Deep Dive Architecture

The wrapper lives in src/primitives. It imports the class from three (e.g., Mesh) and re‑exports a React component that forwards props via useMemo and useUpdate. Props like position, rotation, or material are translated into Three.js setters during the commit phase.

React‑Three‑Fiber’s reconciler runs on every React render pass. It batches attribute changes, updates the Three.js object graph, and then schedules the next WebGL render via requestAnimationFrame. This means you get React’s declarative model without sacrificing frame‑rate.

Real-World Engineering Examples

• A typical button component in ThreeUI looks like <ThreeUI.Box args={[1,0.2,0.1]} onClick={handle}>…</ThreeUI.Box>. Under the hood it becomes a THREE.Mesh with a BoxGeometry and a MeshStandardMaterial.
• If you need a custom shader, you can drop a <ThreeUI.ShaderMaterial> inside the <Canvas>. The wrapper passes the GLSL strings straight to THREE.ShaderMaterial, and the Fiber node ensures uniform updates on each frame.

Component Catalog Design and Live Interactive Previews

The catalog lives under a top‑level "components" folder. Each UI piece gets its own subfolder with a README, a source file, and a meta.json that Storybook reads.

We spin up a Vite dev server for every component preview. The server runs inside Storybook’s sandbox, so the component never touches the main app bundle.

Deep Dive Architecture

The file‑system layout is simple: components/{ComponentName}/src/index.tsx, components/{ComponentName}/meta.json, components/{ComponentName}/README.md. The meta file declares name, description, tags, and the entry point for Storybook.

The sandbox uses Vite’s middleware mode inside Storybook. A custom preview.tsx mounts the component inside a <Canvas> from @react-three/fiber, then Vite serves the compiled module on the fly.

Real-World Engineering Examples

• Storybook story: export const Default = () => <Canvas><OrbitControls /></Canvas>;

State Management and Interaction Handling with Zustand and the Three.js Event System

Three‑dimensional UI needs a single source of truth for hover, click, and drag state. Zustand gives us that without pulling in a full Redux stack. The store lives outside the render loop, so any object in the scene can read or write UI flags. Because the store is just a plain JavaScript object, you can import it in a mesh file, a controller, or a helper without worrying about React lifecycles.

Three.js does not emit DOM events for meshes. Instead we cast a ray from the camera each frame and test against the scene graph. When the ray hits a mesh we look up its identifier in the Zustand store and toggle the appropriate flag. The store notifies all subscribed listeners – UI panels, tooltip components, or physics helpers – and they react instantly. This pattern keeps interaction logic in one place and lets the visual side stay declarative.

Deep Dive Architecture

Define the store with create from 'zustand'. Include booleans for isHovered, isActive, and a vector for dragOffset. Export getters and setters. Because the store is a singleton, any module can call setState directly.

In the render loop, build a Raycaster, set its origin from the mouse position, and call intersectObjects. If an intersect is found, read the object's name or userData.id, then call the store’s setHover(id, true). On mouseout clear the flag. Click events work the same way, just call setActive.

Real-World Engineering Examples

• A floating button changes material color on hover. The button mesh subscribes to store.hoveredId and swaps between MeshBasicMaterial and MeshStandardMaterial in its onBeforeRender hook.
• A draggable slider updates store.dragOffset on mousemove. The slider’s geometry reads the offset each frame, moving the handle without touching the Three.js scene directly.

Rendering Optimizations: three‑mesh‑ui, GPU Instancing, and Level‑of‑Detail Strategies

Three‑mesh‑ui builds UI geometry on the fly. Each button, panel, or text block becomes a Three.js Mesh. On a desktop you can push 200 elements without breaking 60 fps, but on a phone the draw call count spikes. The trick is to stop creating a new Mesh for every element. Instead, reuse geometry and material, and let the GPU handle the heavy lifting.

InstancedMesh lets you draw thousands of identical objects with a single call. You feed it a base geometry, a material, and an array of transforms. For UI you can pack buttons, icons, and sliders into one InstancedMesh. Pair that with a simple LOD system that swaps a high‑poly mesh for a low‑poly version once the screen‑space size drops below a threshold, and you keep the frame budget tight.

Deep Dive Architecture

three‑mesh‑ui exposes a `UIBlock` class that internally creates a BufferGeometry. By calling `block.set({ width: 1, height: 0.5 })` you get a plane with UVs ready for text. When you need dozens of identical buttons, extract the geometry with `block.geometry.clone()` and feed it to an InstancedMesh. Update each instance's matrix with `instanceMatrix.setMatrixAt(i, matrix)` and flag `instanceMatrix.needsUpdate = true`.

LOD in Three.js works with the `LOD` object. Add two meshes: a full‑resolution button and a low‑poly placeholder. Set the distance thresholds based on typical device DPI. For mobile, start swapping at 0.5 m screen distance; for desktop, push it to 1 m. The LOD object automatically chooses the right mesh each frame.

Real-World Engineering Examples

• A game menu with 120 buttons rendered as a single InstancedMesh stayed above 60 fps on an iPhone 12. The only per‑frame work was updating the hover matrix for the focused button.
• An AR overlay with 30 floating panels used three‑mesh‑ui for text layout and an LOD switch that replaced the panel geometry with a simple quad when the user moved beyond 2 m.

Styling and Theming: Design Tokens, Tailwind CSS, and CSS‑in‑JS for 3D UI

When you build a 3D UI with Three.js you quickly discover that colors, spacing, and surface properties have to travel from CSS land into GLSL. A clean way to keep everything in sync is to start with a single source of truth – design tokens – and let the build step generate both Tailwind utilities and JavaScript theme objects. The result feels like regular web styling, but the values end up as shader uniforms at runtime.

The token file lives in src/theme/tokens.json. A tiny node script reads the JSON, writes CSS custom properties, and injects the same values into tailwind.config.js under the extend.colors key. Because Tailwind already knows how to generate utility classes, you can write <button class="bg-primary-500 hover:bg-primary-600"> and the class resolves to a CSS variable that the 3D component reads. The same variable is also exported to a JS object that you spread into a custom <meshStandardMaterial> uniform block. This pipeline guarantees that a change to #primary-500 instantly updates HTML, Tailwind, and the material’s albedo.

Deep Dive Architecture

The token builder runs as an npm script: node scripts/generateTheme.js. It reads tokens.json, creates a CSS file with :root { --color-primary-500: #3b82f6; --spacing-sm: 0.5rem; } and writes a JS module exporting the same map. Tailwind’s config imports that JS module, so every utility class references the CSS variable via the var() function. At runtime, a React hook called useThemeUniform() pulls the JS map, converts pixel values to numbers, and calls material.setUniform('uColor', new THREE.Color(varValue)).

In the shader, you declare uniform vec3 uColor; uniform float uRoughness;. The fragment shader multiplies the albedo by uColor and applies uRoughness to the GGX term. Because the uniform values are updated on every frame when the theme changes, you can toggle dark mode and see the 3D button instantly darken without recompiling the material.

Real-World Engineering Examples

• // tokens.json
  {
  "color-primary-500": "#3b82f6",
  "color-primary-600": "#2563eb",
  "spacing-sm": "0.5rem",
  "material-roughness": "0.2"
  }
• // generateTheme.js (excerpt)
  const fs = require('fs');
  const tokens = require('../src/theme/tokens.json');
  const css = ':root {\n' + Object.entries(tokens).map(([k,v])=>` --${k}: ${v};`).join('\n') + '\n}';
  fs.writeFileSync('src/theme/tokens.css', css);
  module.exports = tokens;

Developer Workflow: Monorepo with Nx, Vite HMR, and Storybook for 3D Components

In our ThreeUI catalog we keep everything under a single Nx workspace. The top‑level folder contains three folders: apps/, libs/, and tools/. apps/ holds the demo playground that stitches together the components. libs/ is split into ui/ for generic React wrappers and three/ for raw Three.js primitives. Each library lives in its own folder with a package.json, tsconfig.json and a vite.config.ts that enables hot‑module replacement. Nx generators take care of creating new libs, wiring the tsconfig paths, and adding the library to the affected‑files graph. This layout lets us share code across demos, tests, and documentation without copying files.

The dev loop is built around Vite’s HMR and Storybook’s isolated environment. Running "npm run dev" starts Vite in the apps/three‑playground, and any change in a lib/three component triggers an instant refresh in the browser, preserving the three.js scene state. For UI testing we spin up Storybook with the @storybook/addon-essentials bundle. Addons like @storybook/addon-controls let us tweak material colors or camera positions on the fly, while @storybook/addon-viewport simulates different screen sizes for responsive 3D UI. The result is a tight feedback cycle: code → HMR → visual → tweak → repeat.

Deep Dive Architecture

Nx’s workspace.json defines two targets for each lib: build (tsc) and storybook (storybook). The affected command (nx affected:test) walks the dependency graph, so only the libs that changed get rebuilt, saving minutes on CI. The vite.config.ts in libs/three uses the defineConfig helper, sets optimizeDeps.include for three, and adds the plugin vite-plugin-glsl to import shader files as strings, which Vite can hot‑replace without a full page reload.

Storybook’s main.js extends Vite’s config via the builder-vite preset. We enable the "hmr" flag and add the "@storybook/addon-interactions" addon to run Jest‑like interaction tests on 3D components. The preview.js file registers a global decorator that wraps every story in a <Canvas> component from @react-three/fiber, ensuring a consistent rendering context across stories.

Real-World Engineering Examples

• Creating a new 3D button: run "nx g @nrwl/react:lib button --directory=libs/three". The generator scaffolds Button.tsx, adds a Storybook story in Button.stories.tsx, and updates tsconfig.base.json. Start "npm run storybook" and you’ll see the button rendered inside a three.js scene with live controls for size and color.
• Running the playground: "npm run dev" launches Vite at http://localhost:5173. Open a component in libs/three/mesh/Box.ts and change the geometry size. Vite HMR swaps the module, and the box updates instantly in the playground without a full reload.

Community Contributions: PR Process, GitHub Actions CI/CD, and Automated Testing with Jest & Playwright

When you open a PR against the threeui repo, the first thing you’ll see is the contribution checklist in the PR template. It forces you to run npm run lint locally, update the CHANGELOG, and add or update unit and visual regression tests. The checklist lives in .github/PULL_REQUEST_TEMPLATE.md and is enforced by a required status check in branch protection rules.

Every push to a PR triggers the threeui-ci.yml workflow. The workflow lints the code, runs Jest unit tests, runs Playwright visual regression tests against a headless Chromium container, and, on merge, publishes the updated catalog to GitHub Pages. The pipeline is fully declarative and runs on Ubuntu‑latest runners, so you don’t need any local Docker setup to see it work.

)

Run npm run lint && npm run test before you push – it saves the CI from failing early and speeds up review.

Never merge a PR that has a red check on the CI workflow; it indicates broken lint or failing tests.

The lint step uses ESLint with the @typescript-eslint/parser and Prettier for formatting. The config lives in .eslintrc.cjs and .prettierrc. The CI runs eslint --max-warnings=0 to treat any warning as a failure, keeping the codebase clean.

Jest handles all unit tests under src/**/*.test.ts. Playwright is configured in playwright.config.ts to capture screenshots for each component story. The CI compares new screenshots to the baseline stored in tests/screenshots/base. If any diff exceeds the threshold, the job fails and uploads the diff as an artifact for review.

A contributor added a new Button component. They ran npm run test:unit to generate a Jest snapshot, then npm run test:visual to capture a Playwright screenshot. The PR passed all checks and merged without manual intervention.

During a release, a flaky Playwright test caused the CI to fail. The maintainer added a retry: 2 option in the Playwright step, fixing the issue and keeping the pipeline reliable.

pros_and_cons

| Feature | Jest | Playwright |
|---|---|---|
| Test type | Unit & snapshot | End‑to‑end & visual |
| Runtime | Node.js | Headless browsers |
| Speed | Fast (ms) | Slower (s) |
| Use case | Logic

props | Layout

CSS |

yaml

name: threeui-ci
on:
pull_request:
branches:

main

n push:
branches:

main

njobs:
lint-test:
runs-on: ubuntu-latest
steps:
- uses: actions

/checkout@v4\n - name: Set up Node\n uses: actions/s

etup-node@v4
with:
node-version:

20

n - run: npm ci
- name: Lint
run: npm run lint
- name: Unit tests
run: npm run test:unit
- name: Visual regression
run: npm run test:visual
env:
PLAYWRIGHT_BROWSERS_PATH: 0
- name: Upload artifacts on failure
if: failure()
uses: actions

/upload-artifact@v4\n with:\n name: visual-diffs\n path: tests/s

creenshots

/diff/

Pull Request

Run ESLint & Prettier

n Lint --> Unit

Jest Unit Tests

n Unit --> Visual

Playwright Visual Tests

n Visual --> Deploy

Deploy to GitHub Pages on merge

A tight PR checklist plus GitHub Actions keeps threeui stable

fast

and safe for community contributors.

Production Deployment: Static Hosting on Vercel, Edge Caching, and Asset Optimization

The catalog lives in a Next.js repo. We run `next build && next export` and Vercel drops the `out` folder to its static host.

Vercel automatically puts every file behind its edge CDN. GLTF models and textures get cached at the edge, so the browser never hits the origin again.

Deep Dive Architecture

Webpack bundles the React UI and the three.js runtime into a few kilobytes. The GLTF files stay out of the JavaScript bundle; they are copied unchanged into `public/models`.

During the Vercel build Vercel detects gzip and brotli candidates and serves the compressed version automatically. You can also enable Draco compression in your export pipeline to shrink GLTF size by 60%.

Real-World Engineering Examples

• In `next.config.js` add `assetPrefix: process.env.NEXT_PUBLIC_BASE_PATH || ''` and `images: {disableStaticImages: true}` to keep the UI lean.
• Create a `vercel.json` with a `headers` rule that matches `/models/*` and returns `Cache-Control: public, max-age=31536000, immutable`.

Future Directions: WebGPU Integration, XR Support, and AI‑Generated UI Components

ThreeUI's roadmap puts WebGPU front and center. Starting with Three.js r155, the experimental WebGPURenderer replaces the classic WebGLRenderer. It talks directly to the GPU via the browser's native WebGPU API, cutting latency and opening up compute shaders for UI effects like blur, drop‑shadow, and particle‑based transitions. Because ThreeUI components already live in a scene graph, swapping the renderer is a matter of swapping the canvas context and tweaking material definitions. The API surface mirrors WebGLRenderer—setSize, setPixelRatio, render—so existing code stays readable.

The next milestone is native XR support. Three.js ships with a WebXRManager that can spin up immersive sessions on headset or mobile browsers. By wiring ThreeUI’s component tree into the XR camera’s pose, we can reuse the same UI definitions for AR overlays or VR menus without rewriting layout logic. On the AI side, we’re prototyping a pipeline that feeds component specs into OpenAI’s gpt‑4‑turbo model, which returns JSX‑style React‑Three‑Fiber snippets. Those snippets drop straight into the catalog, letting contributors generate boilerplate UI with a single prompt.

Deep Dive Architecture

WebGPURenderer requires a GPUAdapter and GPUDevice. In practice you instantiate it with const renderer = new THREE.WebGPURenderer({ antialias: true }); await renderer.init(); The init call resolves the adapter and device, then creates a GPURenderPassDescriptor that matches Three.js’s render target format. Materials need to be switched to MeshStandardMaterial or the new MeshPhysicalMaterial with the 'gpu' flag to enable shader compilation under WebGPU.

XR integration hinges on the XRSession’s reference space. Three.js abstracts this via renderer.xr.setSession(session). After the session starts, you call renderer.setAnimationLoop(render) instead of requestAnimationFrame. Inside render you can query renderer.xr.getCamera(camera) to obtain a view matrix that already accounts for head pose. UI components become children of a Group that follows the XR camera, ensuring they stay anchored to the user’s viewport.

Real-World Engineering Examples

• A recent PR added a ThreeUI modal that uses WebGPU’s compute shader to animate a radial blur when opening. The component lives in src/components/ModalGPU.jsx and only required changing the material’s defines to enable the blur kernel. On browsers that fall back to WebGL, the same component gracefully degrades because the material falls back to a standard fragment shader.
• In the XR demo branch, we built a floating toolbar that appears 0.5 m in front of the user. The toolbar is a simple PlaneGeometry with a texture generated by an AI‑prompted script. The script called OpenAI’s chat completion endpoint, sent a JSON schema describing button icons, and received a React‑Three‑Fiber component that renders the texture on the plane.

Frequently Asked Questions

Conclusion & Next Steps

ThreeUI consolidates a wide range of interactive 3D UI elements—buttons, sliders, menus, and more—into a single, open‑source catalog, enabling developers to drop sophisticated visuals into web applications without building from scratch.

The platform’s live demo environment showcases each component in real time, while the complete source code is openly available, fostering a collaborative ecosystem where contributors can extend the library and instantly see their additions reflected in the catalog.

By leveraging ThreeUI, teams accelerate UI development, reduce maintenance overhead, and stay at the forefront of web‑based 3D experiences; explore the catalog today and join the community to shape the future of immersive interfaces.