Here is a comprehensive, HTML-formatted tutorial covering how to use Three.js for 3D on the web. It includes a detailed step-by-step guide, best practices, an FAQ section, and reference tables, all structured for clarity and depth.
“`html
Mastering Three.js: Build Immersive 3D Web Experiences from Scratch
Three.js has revolutionized the way developers approach three-dimensional graphics on the web. Gone are the days when building interactive 3D scenes required deep expertise in low-level WebGL, complex shader programming, and painful cross-browser compatibility workarounds. Three.js abstracts all that complexity into a clean, well-documented JavaScript library that lets you create stunning 3D visualizations, product configurators, data dashboards, games, and even virtual reality experiences using nothing more than a modern browser. Whether you are a front-end developer looking to add a wow factor to your portfolio, a data scientist who wants to visualize complex datasets in three dimensions, or a creative coder eager to push the boundaries of what the web can do, Three.js provides the tools you need without forcing you to become a graphics programming expert.
In this comprehensive guide, we will walk through everything you need to know to start building 3D applications with Three.js. You will learn how to set up a scene, create and manipulate objects, apply materials and lighting, add interactivity with raycasting, and optimize performance for real-time rendering. We will also cover best practices that professional developers use in production and answer frequently asked questions that trip up beginners. By the time you finish reading, you will have the confidence to build your own 3D web projects from scratch. Let’s begin our journey into the third dimension.
What is Three.js and Why Should You Use It?
Three.js is a cross-browser JavaScript library and application programming interface (API) used to create and display animated 3D computer graphics in a web browser. It uses WebGL under the hood, but it wraps the raw WebGL calls into intuitive high-level objects like scenes, cameras, meshes, lights, and materials. The library was first released by Ricardo Cabello (known as Mr.doob) in 2010 and has since grown into the most popular 3D library on the web, with a massive community, extensive documentation, and thousands of examples. One of the greatest strengths of Three.js is its balance between power and accessibility. You can create a rotating cube with fewer than twenty lines of code, yet you can also build advanced effects like post-processing, shadows, particle systems, and physically-based rendering (PBR) that rival desktop applications.
Why should you choose Three.js over raw WebGL or other libraries like Babylon.js? First, Three.js has the largest ecosystem, which means more tutorials, more community extensions, and more pre-built components. Second, it is framework-agnostic, so you can integrate it with React (via react-three-fiber), Vue, Angular, or vanilla JavaScript. Third, it has excellent documentation and a huge collection of official examples that demonstrate virtually every feature. Fourth, it supports a wide range of 3D model formats including glTF, OBJ, FBX, Collada, and STL, making it easy to import assets from Blender, Maya, or SketchUp. Finally, Three.js has a gentle learning curve compared to writing raw WebGL, and its API is consistent and well-thought-out. Whether you are building a simple product viewer or a complex multiplayer game, Three.js gives you a solid foundation.
Step-by-Step Guide: Building a 3D Scene with Three.js
Step 1: Setting Up Your Development Environment
Before you can start coding, you need to set up a project environment. Three.js can be used in several ways: you can include it via a CDN link in a simple HTML file, install it as an npm package for a more advanced build pipeline, or use it with module bundlers like Webpack or Vite. For beginners, the fastest way to get started is to use a CDN. Create a new HTML file and include the Three.js core library using a script tag. As of 2025, the recommended CDN is unpkg or cdnjs, and you should always specify a version to avoid breaking changes. For example, you can use https://unpkg.com/three@0.160.0/build/three.module.js if you are using ES modules, or the classic build with https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js for older-style scripts. In this tutorial, we will use the ES module approach because it is cleaner and more modern. Create a minimal HTML file with a container div, import Three.js, and set up a basic renderer.
For those who prefer a more professional setup, you can initialize a project with npm. Run npm init -y in your project folder, then npm install three. This will install the latest version into your node_modules. You can then import Three.js in your JavaScript file using import * as THREE from 'three';. If you are using Vite as your build tool (which we highly recommend for its speed and simplicity), your setup is even easier: just create a new Vite project with npm create vite@latest and select the vanilla JavaScript template. Then install Three.js and start coding. Regardless of which method you choose, the core concepts remain identical. Once your environment is ready, it is time to create the four essential components of any Three.js application: the scene, the camera, the renderer, and an object.
Step 2: Creating the Scene, Camera, and Renderer
Every Three.js application revolves around three fundamental objects: a Scene, a Camera, and a Renderer. The Scene is a container that holds all the objects, lights, and backgrounds. Think of it as your 3D world. The Camera defines the viewpoint from which the scene is rendered. Three.js offers several camera types, but the most common are PerspectiveCamera (which mimics human vision with perspective distortion) and OrthographicCamera (which renders without perspective, useful for 2D-like views or technical diagrams). The Renderer takes the scene and camera and draws the image onto an HTML canvas element. WebGLRenderer is the standard choice. Let’s create these three objects step by step.
First, define a Scene: const scene = new THREE.Scene();. You can optionally set a background color using scene.background = new THREE.Color(0x1a1a2e);. Next, create a PerspectiveCamera. The constructor takes four parameters: field of view (FOV) in degrees, aspect ratio (width / height), near clipping plane, and far clipping plane. A typical setup looks like this: const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);. The camera starts at the origin (0,0,0), so you need to move it back so you can see the scene: camera.position.set(0, 2, 5);. Finally, create a WebGLRenderer: const renderer = new THREE.WebGLRenderer({ antialias: true });. Set its size to match the window, and append the canvas to your HTML document: renderer.setSize(window.innerWidth, window.innerHeight); document.body.appendChild(renderer.domElement);. Now you have a blank 3D canvas. To make it responsive, add a window resize listener that updates the camera aspect ratio and renderer size.
Step 3: Adding Geometry, Material, and Mesh
With the scene, camera, and renderer ready, you can start adding 3D objects. In Three.js, any visible object is a Mesh, which is a combination of a Geometry (the shape) and a Material (the surface appearance). Three.js provides a wide variety of geometries: BoxGeometry, SphereGeometry, CylinderGeometry, PlaneGeometry, TorusGeometry, and many more. For materials, you have options like MeshBasicMaterial (no lighting), MeshStandardMaterial (PBR-based, works with lights), MeshPhongMaterial (classic Phong shading), and MeshPhysicalMaterial (advanced PBR with clearcoat, roughness, metalness). Let’s create a simple rotating cube as your first object.
Create a box geometry with dimensions 1x1x1: const geometry = new THREE.BoxGeometry(1, 1, 1);. Then create a material. We will use MeshStandardMaterial so that lighting affects the cube: const material = new THREE.MeshStandardMaterial({ color: 0xe94560, roughness: 0.4, metalness: 0.1 });. Now combine them into a mesh: const cube = new THREE.Mesh(geometry, material);. By default, the cube is placed at the origin (0,0,0). Add it to the scene: scene.add(cube);. If you render right now, you would see nothing because there is no light — MeshStandardMaterial requires lights to be visible. So let’s add some lights. A basic ambient light provides overall illumination: const ambientLight = new THREE.AmbientLight(0xffffff, 0.4); scene.add(ambientLight);. Then add a directional light to create shadows and highlights: const dirLight = new THREE.DirectionalLight(0xffffff, 1.0); dirLight.position.set(5, 10, 7); scene.add(dirLight);. Now you have a visible cube. To see it in motion, you need an animation loop.
Step 4: Creating an Animation Loop and Rendering
Three.js uses a rendering loop to update the scene 60 times per second (or whatever the monitor’s refresh rate allows). The most common approach is to use requestAnimationFrame, which tells the browser to call your render function before the next repaint. Inside this loop, you can update object positions, rotations, scales, or any other property, and then call renderer.render(scene, camera);. This creates real-time interactive graphics. Let’s make our cube rotate by incrementing its rotation properties each frame.
Write a function called animate that does three things: calls requestAnimationFrame(animate) for the next frame, updates the cube’s rotation by adding a small delta, and renders the scene. Here is the code skeleton: function animate() { requestAnimationFrame(animate); cube.rotation.x += 0.01; cube.rotation.y += 0.01; renderer.render(scene, camera); } animate();. This will make the cube spin smoothly along both the X and Y axes. If you run the page, you should see a nicely lit red cube rotating in the center of the viewport. Congratulations — you have created your first real-time 3D scene with Three.js! From here, you can experiment with different geometries, materials, and transformation properties.
Step 5: Adding Interactivity with Raycaster and Mouse Events
A static 3D scene is cool, but true web experiences need interactivity. Three.js provides the Raycaster class to detect mouse clicks, hovers, and touches on 3D objects. The raycaster works by casting an invisible ray from the camera through the mouse position into the scene, and then checking which objects intersect that ray. This is the foundation for clickable buttons, drag-and-drop, tooltips, and game interactions. Let’s add a simple hover effect that changes the cube’s color when the mouse is over it.
First, create a Raycaster and a Vector2 for the mouse position: const raycaster = new THREE.Raycaster(); const mouse = new THREE.Vector2();. Then add an event listener for ‘mousemove’ on the canvas or the window. In the listener, convert the mouse coordinates to normalized device coordinates (NDC) where x and y range from -1 to 1: mouse.x = (event.clientX / window.innerWidth) * 2 - 1; mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;. In your animation loop (or in a separate update function), update the raycaster with the camera and mouse: raycaster.setFromCamera(mouse, camera);. Then compute intersections with the objects you want to interact with: const intersects = raycaster.intersectObjects([cube]);. If the array is not empty, the mouse is over the cube. Change the material color for feedback, and reset it when the mouse leaves. You can use cube.material.color.setHex(0xffaa00); for hover and cube.material.color.setHex(0xe94560); for normal. This simple interaction opens the door to sophisticated UI and game mechanics.
Step 6: Loading and Displaying 3D Models
While primitive geometries are great for learning, real-world projects often use complex 3D models created in external tools like Blender, Maya, or Cinema 4D. Three.js supports many model formats, but the preferred format is glTF (GL Transmission Format) because it is efficient, supports PBR materials, and can include animations. To load a glTF model, you need to use the GLTFLoader, which is part of the examples add-on. First, import the loader: import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';. Then create an instance and call loader.load('path/to/model.glb', callback). The callback receives the loaded scene, which you can add directly to your main scene.
Here is an example: const loader = new GLTFLoader(); loader.load('models/robot.glb', (gltf) => { scene.add(gltf.scene); }, undefined, (error) => { console.error(error); });. You may need to adjust the model’s scale, position, or rotation after loading. Many models come with animations, which you can play using three.js’s AnimationMixer. Loading models asynchronously requires careful handling, but it allows you to incorporate high-quality assets into your web experience. Always ensure your model files are optimized for the web — heavy polygon counts can ruin performance. Tools like Blender’s decimate modifier or online compressors can help reduce file size while preserving visual quality.
Step 7: Implementing Shadows for Realism
Shadows add a tremendous amount of depth and realism to 3D scenes. Three.js supports both directional and spot light shadows, as well as point light shadows. To enable shadows, you need to set several properties. First, enable shadow mapping on the renderer: renderer.shadowMap.enabled = true;. Then, tell the light to cast shadows: dirLight.castShadow = true;. Set the shadow map size for quality: dirLight.shadow.mapSize.width = 1024; dirLight.shadow.mapSize.height = 1024;. Also define the shadow camera frustum — the area where shadows are calculated: dirLight.shadow.camera.near = 0.1; dirLight.shadow.camera.far = 25; dirLight.shadow.camera.left = -10; dirLight.shadow.camera.right = 10; dirLight.shadow.camera.top = 10; dirLight.shadow.camera.bottom = -10;. For the objects, set mesh.castShadow = true on the cube and mesh.receiveShadow = true on the ground plane. Create a ground plane using new THREE.PlaneGeometry(10, 10) with a MeshStandardMaterial. Rotate it to be horizontal: ground.rotation.x = -Math.PI / 2;. Add it to the scene. Now your cube will cast a crisp shadow onto the ground, creating a professional-looking scene.
Tips and Best Practices for Three.js Development
1. Optimize Performance with Geometry Merging and Instancing
When you have hundreds or thousands of objects in a scene, draw calls can quickly become a bottleneck. Three.js provides several techniques to reduce draw calls. Geometry merging (or BufferGeometry merging) combines multiple geometries into a single geometry, which can be rendered in one draw call. For repeated objects that share the same geometry but have different transformations (like a forest of trees or a field of particles), use InstancedMesh. InstancedMesh renders the same geometry multiple times with different transform matrices in a single draw call, drastically improving performance. Always profile your scene using the browser’s developer tools or the Three.js Stats panel to identify bottlenecks.
2. Use LOD (Level of Detail) for Complex Models
If your scene contains models that are far from the camera, you can switch to lower-detail versions to save GPU cycles. Three.js provides the LOD class (Level of Detail) that automatically swaps between different geometry representations based on the distance from the camera. Create multiple versions of your model with decreasing polygon counts, and add them as levels to the LOD object. This is especially useful for large open-world scenes or when displaying many detailed characters. The transition between levels should be smooth to avoid popping artifacts.
3. Always Dispose of Resources When Removing Objects
One of the most common memory leak sources in Three.js applications is failing to properly dispose of geometries, materials, and textures when they are no longer needed. When you remove an object from the scene, call geometry.dispose() and material.dispose() to free GPU memory. Textures also need to be disposed: texture.dispose(). If you are using a render target or a depth texture, dispose those as well. Neglecting this can cause your application to consume ever-increasing memory, leading to crashes or slowdowns. Make disposal a habit, especially in dynamic scenes where objects are created and destroyed frequently.
Common Three.js Objects and Properties Reference
| Component | Class / Constructor | Key Properties | Common Use Case |
|---|---|---|---|
| Scene | THREE.Scene() | background, fog, children | Container for all objects |
| Perspective Camera | THREE.PerspectiveCamera(fov, aspect, near, far) | position, rotation, zoom | First-person view, games |
| WebGLRenderer | THREE.WebGLRenderer({antialias: true}) | setSize, shadowMap, toneMapping | Rendering to canvas |
| Box Geometry | THREE.BoxGeometry(width, height, depth) | parameters: widthSegments, etc. | Cubes, crates, buildings |
| MeshStandardMaterial | THREE.MeshStandardMaterial({color, roughness, metalness}) | color, roughness, metalness, map | PBR-based realistic surfaces |
| DirectionalLight | THREE.DirectionalLight(color, intensity) | position, target, castShadow | Simulating sunlight |
| Raycaster | THREE.Raycaster() | setFromCamera, intersectObjects | Mouse picking, interaction |
Performance Comparison: Rendering Strategies
| Strategy | Draw Calls | Memory Usage | Best For | Complexity |
|---|---|---|---|---|
| Individual Meshes | High (bad) | Low per mesh | < 100 objects | Very simple |
| Geometry Merging | Low (1 per merged group) | High (combined) | Static scenes with many objects | Medium |
| InstancedMesh | Low (1 per instance group) | Medium (shared geo + per-instance data) | Repeated objects (trees, particles) | Medium-High |
| LOD | Variable | Medium (multiple geo copies) | Large worlds with distant objects | High |
Frequently Asked Questions (FAQ)
No, you do not need to know WebGL to use Three.js effectively. The entire purpose of Three.js is to abstract away the complexities of WebGL. However, having a basic understanding of how 3D graphics work (vertices, normals, textures, shaders) will help you debug issues and optimize your scenes. For most common tasks like creating objects, adding lights, and loading models, you can work entirely with Three.js’s high-level API without ever writing a WebGL call.
To handle window resizing, listen for the ‘resize’ event on the window object. Inside the event handler, update the camera’s aspect ratio to match the new window dimensions and call camera.updateProjectionMatrix(). Then update the renderer size: renderer.setSize(window.innerWidth, window.innerHeight). If you are using a Canvas that is not fullscreen, you will need to calculate the correct width and height based on your container element. This ensures your 3D scene scales correctly without distortion.
Yes, absolutely. Three.js can be integrated with any JavaScript framework. For React, the most popular approach is to use react-three-fiber (R3F), which is a React renderer for Three.js. R3F lets you declare Three.js objects as JSX components and manages the render loop and lifecycle for you. For Vue, there is TroisJS and the more recent VueThree. For Angular, you can use ngx-three or simply wrap Three.js code in Angular services and components. In all cases, you need to be mindful of the framework’s lifecycle and avoid memory leaks by properly disposing of Three.js resources.
There are several ways to display text in Three.js. You can use TextGeometry to create 3D text that behaves like any other mesh, but you need to load a font. Alternatively, you can use CSS2DRenderer or CSS3DRenderer to overlay HTML/CSS elements on top of your 3D scene, which is great for labels and tooltips. Another approach is to use sprite-based text with CanvasTexture, where you draw text onto a 2D canvas and then use that canvas as a texture on a plane or sprite. Each method has trade-offs in terms of performance, readability, and interactivity.
Mobile optimization requires careful attention to performance. Start by reducing polygon counts and texture sizes. Use compressed textures (KTX2 or Basis) to reduce GPU memory bandwidth. Limit the number of lights and use efficient shadow map resolutions (512 or 1024). Enable pixel ratio capping: renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) to avoid rendering at ultra-high resolutions on devices with Retina displays. Use geometry instancing for repeated objects and prefer MeshStandardMaterial over MeshPhysicalMaterial when possible. Finally, use the browser’s performance profiler and Three.js Stats to identify bottlenecks specific to mobile hardware.
For complex animations, Three.js provides the AnimationMixer, AnimationClip, and AnimationAction system. You can load animated models (glTF with animations) and play, blend, and cross-fade between animation clips. You can also use the TWEEN library (or the modern gsap) to tween property values over time. For skeleton-based animations, the AnimationMixer handles skinning and bone transforms. Additionally, you can create custom animation loops by updating object properties manually using sine/cosine functions or easing equations for organic motion. For complex character animation, consider using Blender to create the animations and export them as glTF.
One common pitfall is incorrect scaling. Many modeling tools use different units (centimeters vs. meters), so a model may appear too large or too small. Always check the model’s scale and adjust it with gltf.scene.scale.set(0.01, 0.01, 0.01) if necessary. Another issue is missing textures, which happens when the model references external texture files with absolute paths or unsupported formats. Use relative paths and convert textures to JPEG or PNG. Also, be aware that some models contain multiple nested groups, so you may need to traverse the scene to find specific meshes. Finally, ensure that your model is optimized — heavy polygon counts and large texture files can kill frame rates. Use tools like glTF-Transform or Draco compression to reduce file size.
Conclusion
Three.js has democratized 3D graphics on the web, making it possible for any developer with basic JavaScript skills to build immersive, interactive experiences that run directly in the browser. In this tutorial, we covered the entire pipeline: from setting up a development environment and creating a basic scene with a camera and renderer, to adding geometries, materials, and lights, animating objects, implementing mouse interaction with raycaster, loading external 3D models, and enabling realistic shadows. We also discussed performance optimization strategies like instancing, LOD, and proper resource disposal, and answered common questions that beginners often struggle with. The journey from a simple rotating cube to a fully interactive 3D web application is surprisingly short, and the creative possibilities are virtually endless.
As you continue to explore Three.js, you will discover advanced topics like post-processing (bloom, depth of field, ambient occlusion), particle systems for smoke and fire, shader programming with custom GLSL, and integration with WebXR for virtual reality and augmented reality. The official Three.js documentation and the massive collection of examples on the Three.js website are invaluable resources. Join the community on Discord, GitHub, and forums to share your work and learn from others. The most important step is to start building — pick a small project, iterate on it, and gradually push your boundaries. The web is ready for 3D, and Three.js is the key that unlocks it.
Happy coding, and welcome to the third dimension.
“`
