react-3d-dice

3D dice renderer for React using Three.js. Renders D4, D6, D8, D10, D12, and D20 with canvas-textured face labels, settle animations, and optional D6 dot pips.

Install

npm install react-3d-dice three

Peer dependencies: react >= 17, react-dom >= 17, three >= 0.150

Quick Start

import { useState } from 'react';
import Dice3D from 'react-3d-dice';

function App() {
  const [results, setResults] = useState([]);
  const [isRolling, setIsRolling] = useState(false);
  const [trigger, setTrigger] = useState(0);

  const roll = () => {
    setIsRolling(true);
    const newResults = Array.from({ length: 2 }, () =>
      Math.floor(Math.random() * 6) + 1
    );
    setResults(newResults);
    setTrigger(t => t + 1);
    setTimeout(() => setIsRolling(false), 800);
  };

  return (
    <div>
      <Dice3D
        sides={6}
        color={0x3b82f6}
        results={results}
        isRolling={isRolling}
        rollTrigger={trigger}
      />
      <button onClick={roll}>Roll 2D6</button>
    </div>
  );
}

Props

Prop	Type	Default	Description
sides	number	(required)	Number of sides: 4, 6, 8, 10, 12, 20
color	number | string	0x3b82f6	Die color as hex number or CSS hex string
results	number[]	[]	Roll results (one per die rendered)
isRolling	boolean	false	Whether dice are currently rolling
animationMode	'full' | 'quick' | 'none'	'full'	Animation style
rollTrigger	number	0	Increment to trigger a new roll
d6Style	'numbers' | 'dots'	'numbers'	D6 label style (numbers or dot pips)
height	number	auto	Container height in px
className	string	undefined	CSS class for the container
style	object	undefined	Inline styles merged onto container
emptyText	string	'Press Roll...'	Text when no results

Supported Dice

Die	Geometry	Labels
D4	Tetrahedron	Face numbers
D6	Cube	Numbers or dot pips
D8	Octahedron	Face numbers
D10	Pentagonal trapezohedron	Face numbers (odds top, evens bottom)
D12	Dodecahedron	Face numbers
D20	Icosahedron	Face numbers
Other	Icosahedron (unlabeled)	Overlay numbers

Opposite faces always sum to N+1 (e.g. D6: 7, D20: 21).

Engine API

For advanced usage (custom Three.js scenes), import engine utilities:

import { buildDieMesh, settleQuat, createGeometry } from 'react-3d-dice';

// Build a die mesh for your own scene
const mesh = buildDieMesh(20, 0xef4444, 'numbers');
scene.add(mesh);

// Get settle quaternion for a result
const quat = settleQuat(mesh, 17, 20);
mesh.quaternion.copy(quat);

Engine Exports

Export	Description
buildDieMesh(sides, color, d6Style)	Create a complete die mesh with edges and labels
settleQuat(mesh, result, sides)	Get quaternion to show a specific face
createGeometry(sides)	Create raw Three.js geometry
createD10Geometry(radius)	Pentagonal trapezohedron geometry
computeFaces(geometry, numFaces)	Extract face data (centroid, normal, vertices)
computeFaceNumbers(faces, sides)	Assign numbers with opposite-face pairing
faceSettleQuat(face, sides)	Settle quaternion for a single face
parseColor(color)	Convert hex string/number to Three.js color int
clearTextureCache()	Dispose cached canvas textures
getNumTexture(num) / getDotTexture(num)	Get cached canvas textures

How It Works

• Uses OrthographicCamera for zero perspective distortion
• Face labels are canvas textures on PlaneGeometry meshes positioned at face centroids
• Normal-direction clustering detects geometric faces on non-indexed polyhedra
• Vertex-snapping orients numbers to align with face polygon vertices (D4/D8/D12/D20)
• D10 uses custom pentagonal trapezohedron geometry with pole-based text orientation
• Settle animation uses quaternion slerp with cubic ease-out

License

MIT