drei-use-gltf

Use useGLTF for model loading with preloading.

Why It Matters

useGLTF from Drei provides:

• Suspense integration (automatic loading states)
• Caching (same model loaded once)
• Preloading capability
• Draco decompression support

Basic Example

import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene, nodes, materials } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

Preloading (Critical for UX)

import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

// Preload at module level - starts loading immediately
useGLTF.preload('/model.glb');

// Or preload multiple models
useGLTF.preload(['/model1.glb', '/model2.glb', '/model3.glb']);

With Draco Compression

function DracoModel() {
  // Second argument is the Draco decoder path
  const { scene } = useGLTF('/model.glb', '/draco/');
  return <primitive object={scene} />;
}

useGLTF.preload('/model.glb', '/draco/');

Accessing Nodes and Materials

function Character() {
  const { nodes, materials } = useGLTF('/character.glb');

  return (
    <group>
      <mesh
        geometry={nodes.Body.geometry}
        material={materials.Skin}
      />
      <mesh
        geometry={nodes.Clothes.geometry}
        material={materials.Fabric}
      />
    </group>
  );
}

Clone for Multiple Instances

function Tree({ position }) {
  const { scene } = useGLTF('/tree.glb');

  // Clone to avoid sharing state between instances
  return <primitive object={scene.clone()} position={position} />;
}

function Forest() {
  return (
    <>
    </>
  );
}

With Suspense

import { Suspense } from 'react';
import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

function Scene() {
  return (
    <Suspense fallback={<LoadingBox />}>
  );
}

function LoadingBox() {
  return (
    <mesh>
      <boxGeometry />
      <meshBasicMaterial wireframe color="white" />
    </mesh>
  );
}

TypeScript Types

import { useGLTF } from '@react-three/drei';
import { GLTF } from 'three-stdlib';

type GLTFResult = GLTF & {
  nodes: {
    Body: THREE.Mesh;
    Head: THREE.Mesh;
  };
  materials: {
    Skin: THREE.MeshStandardMaterial;
  };
};

function Model() {
  const { nodes, materials } = useGLTF('/model.glb') as GLTFResult;
  // Now nodes.Body and materials.Skin are typed
}

Dispose Handling

R3F auto-disposes by default. To prevent disposal (for shared models):

function SharedModel({ model }) {
  return <primitive object={model} dispose={null} />;
}

References

• Drei useGLTF
• gltfjsx - Generate JSX from GLTF