3d

Render 3D scenes and models that stay smooth on phones and fall back when WebGL is missing.

InterfaceClientBuilt onReact Three Fiberthree.js
/play/3d/brand-cube
A spinning cube coloured by a CSS variable. It pauses when scrolled out of view.

What it is

@kitr/3d renders 3D scenes in React. Put a <Scene> on the page, add meshes and lights, load models with useModel(). It draws only when something changes, pauses off screen, and goes still for people who ask for less motion.

Runs in the browser on every kitr platform. Renders nothing on the server, so pages still prerender.

Install

kitr add 3d

First time? Run npm i -g @kitr/kitr once. Inside a project, the global kitr runs your project's own version.

Adds @kitr/3d with three.js, React Three Fiber and drei. No provider, no config file. Every change.

Quick start

A turning cube in the brand colour. Give the scene a height:

// app/components/brand-cube.tsx
import { Scene, useFrame, useThemeColor } from '@kitr/3d'
import { useRef } from 'react'
import type { Mesh } from 'three'

function Cube() {
  const ref = useRef<Mesh>(null)
  const primary = useThemeColor('--kitr-color-primary')
  useFrame((_, delta) => {
    if (ref.current) ref.current.rotation.y += delta * 0.6
  })
  return (
    <mesh ref={ref} rotation={[0.4, 0, 0]}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={primary} />
    </mesh>
  )
}

export function BrandCube() {
  return (
    <Scene style={{ height: 320 }} fallback={<img src="/images/cube.png" alt="The Acme cube" />}>
      <ambientLight intensity={0.6} />
      <directionalLight position={[2, 3, 2]} intensity={1.4} />
      <Cube />
    </Scene>
  )
}

The cube turns in the theme's primary colour. Without WebGL the fallback shows instead. Off screen, drawing stops. Next in the guide: Show your first scene.

Built on

Library What it gives you What kitr adds
three.js Geometry, materials, lights, cameras and the WebGL renderer. Nothing: it is the engine underneath.
React Three Fiber A React renderer for three.js: <mesh>, useFrame, useThree, events. <Scene>, a <Canvas> with kitr's defaults for SSR, visibility, reduced motion and performance.
drei Controls, loaders, staging and dozens of helpers. useModel(), which loads compressed models with a decoder your app serves itself, and useThemeColor(), which hands three.js the colors of your theme.

kitr 3d:decoders keeps the Draco and KTX2 decoders in public/, so models load with no CDN.

Problems it solves

For movement of ordinary DOM elements, such as a dialog opening or a list re-sorting, use animation instead; three.js is for scenes with a camera.

Further reading