React Three Fiber Loaders

Quick Start

import { Canvas } from '@react-three/fiber'
import { useGLTF, OrbitControls } from '@react-three/drei'
import { Suspense } from 'react'

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

export default function App() {
  return (
    <Canvas>
      <ambientLight />
      <Suspense fallback={null}>
        <Model />
      </Suspense>
      <OrbitControls />
    </Canvas>
  )
}

useGLTF (Drei)

The recommended way to load GLTF/GLB models.

Basic Usage

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

function Model() {
  const gltf = useGLTF('/models/robot.glb')

  // gltf contains:
  // - scene: THREE.Group (the main scene)
  // - nodes: Object of named meshes
  // - materials: Object of named materials
  // - animations: Array of AnimationClip

  return <primitive object={gltf.scene} />
}

Using Nodes and Materials

function Model() {
  const { nodes, materials } = useGLTF('/models/robot.glb')

  return (
    <group>
      {/* Use specific meshes */}
      <mesh
        geometry={nodes.Body.geometry}
        material={materials.Metal}
        position={[0, 0, 0]}
      />
      <mesh
        geometry={nodes.Head.geometry}
        material={materials.Plastic}
        position={[0, 1, 0]}
      />
    </group>
  )
}

With TypeScript (gltfjsx)

Generate typed components using gltfjsx:

npx gltfjsx model.glb --types

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

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

export function Model(props: JSX.IntrinsicElements['group']) {
  const { nodes, materials } = useGLTF('/model.glb') as GLTFResult

  return (
    <group {...props} dispose={null}>
      <mesh geometry={nodes.Body.geometry} material={materials.Metal} />
      <mesh geometry={nodes.Head.geometry} material={materials.Plastic} />
    </group>
  )
}

useGLTF.preload('/model.glb')

Draco Compression

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

function Model() {
  // Drei automatically handles Draco if the file is Draco-compressed
  const { scene } = useGLTF('/models/compressed.glb')
  return <primitive object={scene} />
}

// Or specify Draco decoder path
useGLTF.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/')

Preloading

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

// Preload at module level
useGLTF.preload('/models/robot.glb'