Importing Models in Three.js 3D WebGL

While you can build scenes out of primitive cubes and spheres, you'll eventually want to load real, complex 3D models (like characters or vehicles) made in software like Blender.

Primitive geometries like BoxGeometry or SphereGeometry are great for prototyping, but they can't capture the organic detail of a sculpted character or the precise panel lines of a vehicle. Artists build that geometry in a dedicated 3D content-creation tool, then export it to a format the browser can actually parse.

Importing a model also means importing everything that comes with it — materials, UV-mapped textures, and sometimes animations and a full skeleton — so the loading step is doing a lot more work than just fetching a mesh.

The industry standard format for web 3D models is GLTF (or its binary counterpart, GLB). Think of it as the 'JPEG of 3D' — a format built specifically for efficient transmission and fast loading in real-time applications like browsers and games.

.gltf files are plain JSON describing the scene graph, materials, and animations, with textures and binary buffers referenced as separate external files. .glb instead packs the JSON, binary buffer, and textures into a single binary file, which is usually the better choice on the web since it means one HTTP request instead of several.

Both formats were designed by the Khronos Group to be lightweight to parse and GPU-friendly, unlike older formats like .fbx or .obj, which were built for offline production pipelines rather than runtime delivery.

To load a GLTF model in vanilla Three.js, you use the GLTFLoader. It's not in the core library; you have to import it from the examples folder, since Three.js keeps per-format loaders out of the main bundle to keep it small.

GLTFLoader.load() is asynchronous — it takes a URL and a callback that fires once the file (and any textures it references) has finished downloading and parsing. The resulting gltf object exposes a scene property, which is the THREE.Group you actually add to your scene with scene.add(gltf.scene).

Because loading happens over the network, always wire up the loader's progress and error callbacks too; a bad path or a CORS-blocked texture will otherwise fail silently.

In React Three Fiber, loading models is incredibly easy using the useGLTF hook from @react-three/drei.

Under the hood, useGLTF wraps GLTFLoader in React's Suspense-based data-fetching pattern and caches the result by URL, so calling useGLTF('/model.glb') from multiple components reuses the same parsed geometry instead of re-fetching it. It also supports drei's useGLTF.preload() to start the download before the component even mounts.

The hook returns the same gltf object you'd get from GLTFLoader directly — scene, animations, materials, nodes — just wired into React's render lifecycle instead of a manual callback.

When you load a model via useGLTF, you use the special <primitive> R3F component to render the resulting Three.js object inside your Canvas.

<primitive> is different from R3F's usual declarative tags like <mesh> — instead of building a new Three.js object from JSX props, it takes an already-existing object (in this case gltf.scene, a Group built by the loader) and inserts it directly into the scene graph as-is.

This matters because a loaded GLTF scene can be an arbitrarily deep hierarchy of groups, meshes, and bones you didn't author yourself — <primitive object={gltf.scene} /> drops that whole structure into your React tree in one line rather than requiring you to manually recreate it as JSX.

Because loading a 10MB model takes time, React will throw an error if you don't wrap the model in a <Suspense> boundary.

useGLTF (and drei's other loader hooks) throw a Promise while the asset is still downloading, which is exactly the signal React's Suspense mechanism is built to catch — Suspense pauses rendering of the wrapped subtree and shows the fallback until that Promise resolves.

Without a Suspense boundary above it, that thrown Promise has nowhere to be caught and crashes the render instead of gracefully showing a loading state, so any component using useGLTF needs a Suspense ancestor somewhere in the tree.

Let's see a live preview! We don't have external files here, so we will generate a complex Group programmatically to simulate a 'model', wrapped in Suspense.

A real GLTF import and a hand-built THREE.Group behave identically once they're in the scene graph — both are just a container node with child meshes attached. Wrapping this fake model in Suspense mirrors how a real async-loaded model would be handled, even though this particular group resolves instantly with no network request involved.

It's a useful mental model: whatever nesting of groups and meshes a GLTF file produces, you can traverse, restyle, and animate it exactly the same way you would this synthetic stand-in.

A GLTF model is usually just a giant THREE.Group containing dozens of meshes. You can traverse it to modify specific parts (e.g., changing the color of a car's wheels).

.traverse() walks every descendant of an object recursively, calling your callback once per node — meshes, groups, bones, everything. Checking child.isMesh before touching child.material matters, since not every node in the hierarchy is a mesh with a material to modify.

This pattern relies on the object names assigned by the artist in Blender (or whichever tool exported the model) being preserved in the GLTF export, which is why matching against child.name === 'Wheel' only works if the source file's naming convention is known and consistent.

Awesome! You now know how to bring massive, artist-created models into the browser. Next up: letting the user explore them with Camera Controls!

Loading the model is really just the first half of the equation — a beautifully detailed import sitting behind a fixed, un-orbitable camera doesn't showcase much. Interactive controls are what let a viewer actually walk around and appreciate the geometry you just learned to load.

Keep in mind that real-world assets are rarely as clean as this synthetic example: expect to deal with mismatched scale, baked-in rotations, and compressed geometry (via DRACOLoader) as your models grow more complex.

While you can build scenes out of primitive cubes and spheres, you'll eventually want to load real, complex 3D models (like characters or vehicles) made in software like Blender.

The industry standard format for web 3D models is GLTF (or its binary counterpart, GLB). Think of it as the 'JPEG of 3D'.

Which file format is considered the industry standard for loading 3D models on the web efficiently?

• →OBJ
• →glTF / GLB
• →FBX

To load a GLTF model in vanilla Three.js, you use the GLTFLoader. It's not in the core library; you have to import it from the examples folder.

In React Three Fiber, loading models is incredibly easy using the useGLTF hook from @react-three/drei.

When you load a model via useGLTF, which special R3F component do you use to render the resulting Three.js object inside your Canvas?

• →mesh
• →group
• →primitive

Because loading a 10MB model takes time, React will throw an error if you don't wrap the model in a <Suspense> boundary.

Let's see a live preview! We don't have external files here, so we will generate a complex Group programmatically to simulate a 'model', wrapped in Suspense.

A GLTF model is usually just a giant THREE.Group containing dozens of meshes. You can traverse it to modify specific parts (e.g., changing the color of a car's wheels).

Which method allows you to loop through every single child object (meshes, lights, groups) inside a loaded GLTF scene?

• →forEach
• →map
• →traverse

Awesome! You now know how to bring massive, artist-created models into the browser. Next up: letting the user explore them with Camera Controls!