Summarize this article with:
3D graphics used to require specialized software and game engines. Now browsers render interactive 3D experiences natively.
Three.js makes browser-based 3D development accessible to anyone comfortable with JavaScript.
This guide covers scene creation, geometry construction, lighting systems, animation techniques, and performance optimization. You’ll understand how to build everything from simple rotating cubes to complex interactive visualizations.
Whether you’re creating product demos, data visualizations, or web-based games, you’ll learn the core concepts that power real-time 3D rendering on the web.
What is Three.js
Three.js is a JavaScript library that renders 3D graphics directly in web browsers using WebGL.
Created by Ricardo Cabello (Mr.doob) in 2010, it abstracts the complexity of low-level WebGL code into a simple, intuitive API.
Developers build interactive 3D experiences without writing shader programs or managing GPU buffers manually. The library handles rendering pipelines, polygon meshes, and vertex data while you focus on creativity.
Core Architecture Components
Scene Management
See the Pen
Interactive 3D Galaxy Simulation by Voxelo (@VoXelo)
on CodePen.
The Scene acts as a container for all 3D objects, lights, and cameras in your project.
Everything visible gets added to the scene graph, a hierarchical structure that organizes parent-child relationships between objects. Position a parent object and its children move with it.
Camera Systems
PerspectiveCamera mimics human vision with a field of view that creates realistic depth perception.
Takes four parameters: FOV angle (typically 45-75 degrees), aspect ratio (viewport width divided by height), near clipping plane, and far clipping plane. Objects outside these planes won’t render.
OrthographicCamera provides a flat, isometric view where objects maintain size regardless of distance.
Renderer Implementation
WebGLRenderer converts your scene into pixels displayed on a Canvas element.
Initialize the renderer, set its size to match your viewport, then append it to the DOM. The rendering pipeline processes geometry, applies materials, calculates lighting, and outputs the final frame.
Geometry and Mesh Construction
Built-in Geometries
Three.js includes predefined geometric primitives that speed up development.
BoxGeometry creates cubes and rectangular prisms with width, height, and depth parameters. SphereGeometry generates spheres with radius and segment counts for smoothness control. CylinderGeometry, PlaneGeometry, and TorusGeometry cover most basic shapes.
Custom geometries require defining vertices manually, but built-in options handle 90% of use cases.
Materials and Textures
Materials define how surfaces respond to light and appear to viewers.
MeshBasicMaterial ignores lighting entirely, displaying solid colors. MeshLambertMaterial creates matte, non-shiny surfaces. MeshPhongMaterial adds specular highlights for glossy effects.
Texture mapping wraps images onto 3D surfaces. Load textures asynchronously, apply them to material properties, then watch flat geometry transform into realistic objects.
Mesh Creation
A Mesh combines geometry (shape) with material (appearance) into a renderable 3D object.
const geometry = new THREE.BoxGeometry(2, 2, 2);
const material = new THREE.MeshPhongMaterial({ color: 0x00ff00 });
const mesh = new THREE.Mesh(geometry, material);
Position meshes using .position.set(x, y, z). Rotate with .rotation.x/y/z in radians. Scale uniformly or per-axis with .scale.set().
Lighting Systems
Light Types
AmbientLight illuminates everything equally, creating base visibility without shadows or direction.
DirectionalLight simulates sunlight with parallel rays from a specific direction. PointLight radiates from a single point like a light bulb. SpotLight creates focused cones of illumination.
Light Configuration
Set intensity values (typically 0.2-1.0 for ambient, 0.5-2.0 for directional) to control brightness.
Color values use hexadecimal format (0xffffff for white). Position lights in 3D space using coordinate systems, then target specific objects for dramatic effects.
Shadow casting requires enabling shadows on both the renderer and individual lights.
Animation and Interactivity
Animation Loop
requestAnimationFrame creates smooth motion by syncing renders with the browser’s refresh rate (typically 60fps).
Call the renderer inside the loop, update object properties between frames, and the browser handles timing automatically. This prevents screen tearing and maintains consistent frame rates across devices.
Object Manipulation
Increment rotation values each frame to spin objects: mesh.rotation.y += 0.01.
Modify position for movement, scale for size changes, or combine transformations for complex animations. The JavaScript game loop pattern keeps everything synchronized.
User Interaction
See the Pen
CPChallenge: Bugs (butterflies with threejs-toy) by Tommy Ho (@tommyho)
on CodePen.
OrbitControls lets users rotate the camera around objects with mouse or touch input.
Raycasting detects which 3D objects the user clicks by casting invisible rays from the camera through mouse coordinates. Intersection tests return hit objects, enabling clickable 3D interactive elements.
Loading External Assets
Model Loaders
GLTFLoader imports .gltf and .glb files, the standard format for web 3D models.
OBJLoader handles legacy .obj files but lacks material and animation support. FBXLoader works with Autodesk formats if you need complex character rigs.
Import loaders as separate modules, instantiate them, then call .load() with file paths and callback functions.
Texture Loading
TextureLoader fetches image files asynchronously and converts them into usable textures.
Supports JPG, PNG, and WebP formats. Cube maps require six images (one per face) for environment reflections. Normal maps add surface detail without extra geometry.
Performance Optimization
Rendering Performance
Reduce draw calls by combining similar objects into single geometries using BufferGeometry.
Geometry instancing renders thousands of identical objects with one draw call. LOD (level of detail) swaps high-poly models with simplified versions based on camera distance.
Frustum culling automatically skips objects outside the camera view.
Memory Management
Call .dispose() on geometries, materials, and textures when removing objects from scenes.
Unmanaged resources leak memory and eventually crash browsers. Textures consume the most memory, especially large or numerous ones. Reuse materials across multiple meshes instead of creating duplicates.
Setup and Installation
Installation Methods
Install via npm: npm install three for module bundler projects.
CDN option: <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script> for quick prototypes. ES6 imports work with modern build tools: import * as THREE from 'three'.
Project Structure
Vite provides the fastest development server for Three.js projects with hot module replacement.
Webpack works but requires more configuration. Keep all 3D assets in a /public or /static folder. Organize code into separate files for scenes, objects, and utilities as projects grow.
Common Use Cases
Applications
Web-based 3D games run directly in browsers without plugins or downloads.
Product visualization lets e-commerce sites show items from every angle with zoom and rotation. Architectural walkthroughs replace static renders with interactive building tours.
Data visualization transforms complex datasets into spatial representations. WebXR integration adds VR and AR experiences.
Troubleshooting and Best Practices
Common Issues
Black screens usually mean missing lights on Lambert or Phong materials.
Texture loading fails when file paths are wrong or CORS blocks external images. Performance drops happen when too many objects render simultaneously. Check browser consoles for WebGL capability errors on older devices.
Best Practices
Test across Chrome, Firefox, Safari, and mobile browsers for cross-browser compatibility.
Lazy-load large 3D models to prevent blocking page rendering. Use compressed texture formats (Basis Universal) to reduce download sizes. Profile with browser DevTools to identify bottlenecks before optimizing.
Keep geometry vertex counts reasonable (under 100k triangles per object for real-time performance).
FAQ on Three.js
Is Three.js hard to learn?
Not if you know JavaScript basics. The library abstracts complex WebGL code into simple functions.
Most developers build their first rotating cube within 30 minutes. Advanced features like shaders and physics require more time investment.
What’s the difference between Three.js and WebGL?
WebGL is the low-level browser API for GPU rendering. Three.js wraps WebGL in a JavaScript library that handles scenes, cameras, and materials automatically.
Think of WebGL as assembly language and Three.js as Python.
Can Three.js run on mobile devices?
Yes, it works on iOS and Android browsers. Performance depends on device GPU capabilities and scene complexity.
Optimize geometry and textures for mobile. Test on actual devices, not just desktop browsers with device emulation.
Do I need to know 3D modeling software?
No, but it helps. Three.js includes built-in geometries for basic shapes.
For custom models, tools like Blender export GLTF files that GLTFLoader imports directly. You can build plenty without ever opening modeling software.
How does Three.js compare to Babylon.js?
Both are JavaScript 3D libraries built on WebGL. Babylon.js focuses more on game development with built-in physics engines.
Three.js offers lighter weight and simpler API for general 3D graphics. Choose based on project requirements.
What are the performance limits of Three.js?
Modern GPUs handle 100k+ triangles at 60fps easily. Mobile devices struggle above 50k triangles.
Draw calls matter more than polygon count. Combine meshes, use instancing, and implement LOD systems for large scenes.
Can Three.js create VR experiences?
Yes, through WebXR integration. The library includes VR camera rigs and controller support.
Works with Oculus Quest, HTC Vive, and other headsets. Requires HTTPS hosting and user permission to access VR hardware.
How do I add physics to Three.js?
Three.js doesn’t include physics engines. Integrate third-party libraries like Cannon.js or Ammo.js.
These handle collision detection, gravity, and rigid body dynamics. Synchronize physics objects with Three.js meshes each frame.
Is Three.js good for game development?
Works well for browser games with moderate complexity. Handles 3D environments, character rendering, and basic interactions.
For complex games, consider Phaser (2D) or PlayCanvas (3D with built-in editor). Three.js excels at visualization and interactive experiences.
What file formats does Three.js support?
GLTF/GLB is the recommended format for 3D models. Also supports OBJ, FBX, Collada, and STL.
Texture formats include JPG, PNG, WebP, and compressed formats like KTX2. Use GLTF for best compatibility and features.
Conclusion
Three.js transforms complex 3D web development into something approachable for any developer comfortable with basic programming concepts.
The library handles rendering pipelines, GPU acceleration, and WebGL abstraction while you focus on building experiences. Scene graphs, mesh construction, and lighting systems work together through intuitive APIs.
Start with simple geometric primitives and built-in materials. Progress to custom geometries, texture mapping, and model importing as your skills grow.
Performance optimization matters less in early projects but becomes critical for production applications. Memory management, draw call reduction, and geometry instancing keep frame rates smooth across devices.
Browser-based 3D graphics continue expanding into product visualization, architectural walkthroughs, and interactive data representations. The tools exist now to build whatever you imagine.
