r3f-component-patterns

React Three Fiber Component Patterns

When to Use

Use this skill when:

• Building reusable 3D components with R3F
• Structuring React Three.js applications
• Implementing component composition
• Creating custom R3F hooks
• Optimizing React component performance

Core Principles

1. Declarative: Define 3D scenes with JSX
2. Reusable: Create component libraries
3. Composable: Build complex scenes from simple parts
4. Type-Safe: Full TypeScript support
5. Performance: Use React.memo and useMemo
6. Props-Driven: Configure via props, not imperative code

Implementation

1. Basic Component Patterns

// components/Box.tsx
import { useRef } from 'react';
import { useFrame } from '@react-three/fiber';
import { Mesh } from 'three';

interface BoxProps {
  position?: [number, number, number];
  color?: string;
  scale?: number;
  rotationSpeed?: number;
  onClick?: () => void;
}

export function Box({
  position = [0, 0, 0],
  color = 'hotpink',
  scale = 1,
  rotationSpeed = 1,
  onClick,
}: BoxProps) {
  const meshRef = useRef<Mesh>(null);

  useFrame((state, delta) => {
    if (meshRef.current) {
      meshRef.current.rotation.y += delta * rotationSpeed;
    }
  });

  return (
    <mesh ref={meshRef} position={position} scale={scale} onClick={onClick}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={color} />
    </mesh>
  );
}

2. Compound Components

// components/Player.tsx
import { useRef } from 'react';
import { Group } from 'three';

interface PlayerProps {
  position?: [number, number, number];
  color?: string;
}

export function Player({ position = [0, 0, 0], color = 'blue' }: PlayerProps) {
  const groupRef = useRef<Group>(null);

  return (
    <group ref={groupRef} position={position}>
      {/* Body */}
      <mesh position={[0, 1, 0]} castShadow>
        <boxGeometry args={[1, 2, 1]} />
        <meshStandardMaterial color={color} />
      </mesh>

      {/* Head */}
      <mesh position={[0, 2.5, 0]} castShadow>
        <sphereGeometry args={[0.5, 16, 16]} />
        <meshStandardMaterial color={color} />
      </mesh>

      {/* Arms */}
      <mesh position={[-0.75, 1, 0]} castShadow>
        <boxGeometry args={[0.3, 1.5, 0.3]} />
        <meshStandardMaterial color={color} />
      </mesh>
      <mesh position={[0.75, 1, 0]} castShadow>
        <boxGeometry args={[0.3, 1.5, 0.3]} />
        <meshStandardMaterial color={color} />
      </mesh>
    </group>
  );
}