To run three.js in an HTML5 page, you need no install. Add an import map that says where three lives on a CDN, then write your code in a <script type="module">. three.js creates a <canvas> and draws your 3D scene into it.
Here is the whole thing in one file: a lit cube that turns.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>three.js in one HTML file</title>
<style>
html, body { margin: 0; height: 100%; background: #111827; }
canvas { display: block; width: 100%; height: 100%; }
#ver {
position: fixed; left: 10px; bottom: 8px;
font: 12px system-ui, sans-serif; color: #9ca3af;
}
</style>
<!-- 1. Tell the browser where "three" lives (pinned version) -->
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js"
}
}
</script>
</head>
<body>
<span id="ver"></span>
<!-- 2. Your code must be a module to use import -->
<script type="module">
import * as THREE from 'three';
// scene + camera + renderer: the three things every three.js page needs
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.1, 100);
camera.position.z = 3; // step back, or the camera sits inside the cube
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(devicePixelRatio); // sharp on phones
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement); // the <canvas>
// a cube = geometry (shape) + material (surface)
const cube = new THREE.Mesh(
new THREE.BoxGeometry(1, 1, 1),
new THREE.MeshStandardMaterial({ color: 0x22c55e })
);
scene.add(cube);
// MeshStandardMaterial is black without light
scene.add(new THREE.AmbientLight(0xffffff, 0.6));
const sun = new THREE.DirectionalLight(0xffffff, 2);
sun.position.set(2, 3, 4);
scene.add(sun);
// draw every frame
renderer.setAnimationLoop((time) => {
cube.rotation.x = time / 2000;
cube.rotation.y = time / 1000;
renderer.render(scene, camera);
});
// keep the shape correct when the window changes size
addEventListener('resize', () => {
camera.aspect = innerWidth / innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(innerWidth, innerHeight);
});
document.getElementById('ver').textContent = 'three.js r' + THREE.REVISION;
</script>
</body>
</html>
Copy the complete code into an empty .html file. The library loads from the pinned CDN address, so this one-file example still needs an internet connection. It is not an offline bundle.
What three.js is
three.js is a JavaScript 3D library. Its own README describes the aim as an easy-to-use, lightweight, cross-browser, general-purpose 3D library. It ships WebGL and WebGPU renderers, and it is free under the MIT licence.
"HTML5" here simply means a modern web page. The page gives three.js a <canvas> element and the browser's WebGL support. three.js gives you objects such as scenes, cameras, shapes, materials and lights, so you do not write shader code by hand.
If you want to see what that saves you, WebGL in HTML draws a triangle with no library at all.
The smallest working file, part by part
Every three.js page follows the same order. The official guide puts it as three things you need: a scene, a camera and a renderer.

- Import map. A
<script type="importmap">in the head maps the namethreeto a full CDN address. MDN notes it must come before any module script that uses it. - Module script. Only a
type="module"script may useimport. In a plain script tag, the browser stops at the import line. - Scene, camera, renderer. The renderer creates a canvas. Append
renderer.domElementto the body, and move the camera back from the centre. - Draw loop. Nothing appears until
renderer.render(scene, camera)runs.setAnimationLoopcalls your function on every screen refresh.
The import map from the first example looks like this:
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js"
}
}
</script>
The three.js installation guide explains the import-map setup and matching addon versions. The examples pin three.js to 0.186.1. Keep the core library and addons on the same version and CDN. Test the complete page before changing that version; a newer release can include breaking changes.
Old tutorials use three.min.js
Many older guides start with a plain <script src> pointing at build/three.min.js, then use a global THREE. The three.js migration guide says that build file, along with build/three.js, was removed in r161.

With a current version number, the old address returns 404 and the next line throws THREE is not defined.
The fix keeps the rest of your code. Swap the script tag for the import map above, and put import * as THREE from 'three'; at the top of a module script.
Why the model is black
Sometimes the shape is there, but it is a black silhouette. The sample’s MeshStandardMaterial uses the scene’s lights. It has no environment map or emissive colour, so switching those lights off leaves a black surface.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Why is my three.js mesh black?</title>
<style>
html, body { margin: 0; height: 100%; }
body { display: flex; flex-direction: column; font-family: system-ui, sans-serif; background: #f4f5f7; }
#view { flex: 1; min-height: 0; }
canvas { display: block; width: 100%; height: 100%; }
.bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; padding: 10px 12px; background: #fff; }
button {
font: inherit; font-size: 14px; padding: 8px 12px; border: 1px solid #d1d5db;
border-radius: 8px; background: #fff; cursor: pointer;
}
button[aria-pressed="true"] { background: #0f766e; border-color: #0f766e; color: #fff; }
#note { flex-basis: 100%; font-size: 13px; color: #374151; margin: 0; }
</style>
<script type="importmap">
{ "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js" } }
</script>
</head>
<body>
<div id="view"></div>
<div class="bar">
<button id="light" aria-pressed="true">Lights: on</button>
<button id="mat" aria-pressed="true">Material: Standard</button>
<p id="note"></p>
</div>
<script type="module">
import * as THREE from 'three';
const view = document.getElementById('view');
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xe5e7eb);
const camera = new THREE.PerspectiveCamera(50, 1, 0.1, 100);
camera.position.set(0, 0.5, 5);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(devicePixelRatio);
view.appendChild(renderer.domElement);
// two materials for the same shape
const standard = new THREE.MeshStandardMaterial({ color: 0xf97316 }); // needs light
const basic = new THREE.MeshBasicMaterial({ color: 0xf97316 }); // ignores light
const knot = new THREE.Mesh(new THREE.TorusKnotGeometry(0.8, 0.28, 128, 16), standard);
scene.add(knot);
const lights = new THREE.Group();
lights.add(new THREE.AmbientLight(0xffffff, 0.5));
const sun = new THREE.DirectionalLight(0xffffff, 2.5);
sun.position.set(3, 4, 5);
lights.add(sun);
scene.add(lights);
const lightBtn = document.getElementById('light');
const matBtn = document.getElementById('mat');
const note = document.getElementById('note');
function update() {
const isStd = knot.material === standard;
lightBtn.textContent = 'Lights: ' + (lights.visible ? 'on' : 'off');
lightBtn.setAttribute('aria-pressed', lights.visible);
matBtn.textContent = 'Material: ' + (isStd ? 'Standard' : 'Basic');
matBtn.setAttribute('aria-pressed', isStd);
note.textContent = isStd && !lights.visible
? 'Black: MeshStandardMaterial with no light. Turn a light on.'
: isStd ? 'Shaded: MeshStandardMaterial reacts to the lights.'
: 'Flat: MeshBasicMaterial is not affected by lights.';
}
lightBtn.addEventListener('click', () => { lights.visible = !lights.visible; update(); });
matBtn.addEventListener('click', () => {
knot.material = knot.material === standard ? basic : standard;
update();
});
update();
// size the canvas to its box, not the window
new ResizeObserver(() => {
const w = view.clientWidth, h = view.clientHeight;
renderer.setSize(w, h, false);
camera.aspect = w / h;
camera.updateProjectionMatrix();
}).observe(view);
renderer.setAnimationLoop((t) => {
knot.rotation.y = t / 1500;
renderer.render(scene, camera);
});
</script>
</body>
</html>
| Material | Needs lighting? | Looks like |
|---|---|---|
MeshBasicMaterial |
No | One flat colour, no shading |
MeshNormalMaterial |
No | Colours mapped from the surface direction |
MeshStandardMaterial |
Yes: lights or an environment map | Shaded, with roughness and metalness |
For lit materials, an AmbientLight lights every side equally and a DirectionalLight gives the bright and dark faces. The three.js source notes that MeshBasicMaterial "is not affected by lights".
Size, sharpness and phones
The renderer's canvas has two sizes: how big it looks on the page, and how many pixels it draws. If either is wrong, the scene stretches or looks soft.

- The examples use
setPixelRatio(devicePixelRatio). On a device that struggles with the render load, try capping it withMath.min(devicePixelRatio, 2)and compare the result. More pixels also mean more rendering work. - When the space changes size, call
setSizewith the new width and height, setcamera.aspectto width divided by height, then callcamera.updateProjectionMatrix(). - If the canvas fills a box instead of the window, watch the box with a
ResizeObserver. The second and third examples do this.
Add the viewport meta tag too, or a phone lays the page out at desktop width.
A finished example: a viewer you can turn
Controls, loaders and effects live in the addons folder. The installation guide says addons need no separate install, only a separate import. Add a second entry to the import map for that folder, with the same version.
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.1/examples/jsm/"
Then import OrbitControls and hand it the camera and the canvas. Drag to turn, scroll or pinch to zoom.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>three.js viewer with OrbitControls</title>
<style>
html, body { margin: 0; height: 100%; }
body { display: flex; flex-direction: column; font-family: system-ui, sans-serif; background: #f4f5f7; }
#view { flex: 1; min-height: 0; position: relative; }
canvas { display: block; width: 100%; height: 100%; touch-action: none; }
#hint {
position: absolute; left: 10px; top: 8px; margin: 0;
font-size: 12px; color: #4b5563; pointer-events: none;
}
.bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; padding: 10px 12px; background: #fff; }
.sw { width: 30px; height: 30px; border-radius: 50%; border: 2px solid #fff; box-shadow: 0 0 0 1px #d1d5db; cursor: pointer; }
.sw[aria-pressed="true"] { box-shadow: 0 0 0 2px #111827; }
#reset { font: inherit; font-size: 14px; padding: 7px 12px; border: 1px solid #d1d5db; border-radius: 8px; background: #fff; cursor: pointer; margin-left: auto; }
</style>
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.186.1/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.1/examples/jsm/"
}
}
</script>
</head>
<body>
<div id="view"><p id="hint">Drag to turn. Scroll or pinch to zoom.</p></div>
<div class="bar">
<button class="sw" data-color="#2563eb" style="background:#2563eb" aria-label="Blue" aria-pressed="true"></button>
<button class="sw" data-color="#e11d48" style="background:#e11d48" aria-label="Red" aria-pressed="false"></button>
<button class="sw" data-color="#f59e0b" style="background:#f59e0b" aria-label="Amber" aria-pressed="false"></button>
<button class="sw" data-color="#10b981" style="background:#10b981" aria-label="Green" aria-pressed="false"></button>
<button id="reset">Reset view</button>
</div>
<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const view = document.getElementById('view');
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf8fafc);
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(3, 2.2, 4);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(devicePixelRatio);
view.appendChild(renderer.domElement);
// drag / wheel / pinch moves the camera around the target
const controls = new OrbitControls(camera, renderer.domElement);
controls.target.set(0, 0.6, 0);
controls.enableDamping = true;
controls.minDistance = 2.5;
controls.maxDistance = 10;
controls.update();
controls.saveState(); // remembered for "Reset view"
// a texture drawn in the page: no image file to load
const c = document.createElement('canvas');
c.width = c.height = 128;
const g = c.getContext('2d');
g.fillStyle = '#e2e8f0'; g.fillRect(0, 0, 128, 128);
g.fillStyle = '#cbd5e1'; g.fillRect(0, 0, 64, 64); g.fillRect(64, 64, 64, 64);
const tex = new THREE.CanvasTexture(c);
tex.colorSpace = THREE.SRGBColorSpace;
tex.wrapS = tex.wrapT = THREE.RepeatWrapping;
tex.repeat.set(4, 4);
const floor = new THREE.Mesh(new THREE.PlaneGeometry(6, 6), new THREE.MeshStandardMaterial({ map: tex }));
floor.rotation.x = -Math.PI / 2;
scene.add(floor);
// the object we look at
const paint = new THREE.MeshStandardMaterial({ color: 0x2563eb, roughness: 0.35, metalness: 0.1 });
const knot = new THREE.Mesh(new THREE.TorusKnotGeometry(0.5, 0.18, 160, 20), paint);
knot.position.y = 0.9;
const base = new THREE.Mesh(new THREE.CylinderGeometry(0.7, 0.8, 0.2, 48), new THREE.MeshStandardMaterial({ color: 0x334155 }));
base.position.y = 0.1;
scene.add(knot, base);
scene.add(new THREE.HemisphereLight(0xffffff, 0x94a3b8, 1.2));
const sun = new THREE.DirectionalLight(0xffffff, 2);
sun.position.set(3, 5, 2);
scene.add(sun);
// colour buttons change the material, not the mesh
document.querySelectorAll('.sw').forEach((btn) => {
btn.addEventListener('click', () => {
paint.color.set(btn.dataset.color);
document.querySelectorAll('.sw').forEach((b) => b.setAttribute('aria-pressed', b === btn));
});
});
document.getElementById('reset').addEventListener('click', () => {
// Finish any remaining damped movement before restoring the saved view.
const damping = controls.enableDamping;
controls.enableDamping = false;
controls.update();
controls.reset();
controls.enableDamping = damping;
});
new ResizeObserver(() => {
const w = view.clientWidth, h = view.clientHeight;
renderer.setSize(w, h, false);
camera.aspect = w / h;
camera.updateProjectionMatrix();
}).observe(view);
renderer.setAnimationLoop((t) => {
knot.rotation.y = t / 2500;
controls.update(); // needed every frame when damping is on
renderer.render(scene, camera);
});
</script>
</body>
</html>
- Same version for every file. The guide warns that mixing versions or CDNs can include duplicate code or break the page.
- Damping needs an update call. With
enableDampingon, callcontrols.update()in the draw loop. - No image files. The checkered floor is a
CanvasTexturedrawn by the page itself, so there is nothing extra to load.
Opening the file, and when you need a server
In our tests, every example here ran when opened straight from disk, because all of the code is inline and three.js comes from the CDN. That stops when you split your code into a local main.js file.
Loading a local module from a file:// address is blocked by the browser. MDN describes this as a CORS error and recommends testing through a server. The three.js guide also notes that some features do not work when the page is opened by double-click.
The guide's other route is npm and the Vite build tool. That is the right fit once a project grows into several files. It does not run inside a single HTML file:
npm install --save three
npm install --save-dev vite
npx vite # local dev server
npx vite build # output in dist/
For one page you want to send to someone, inline code plus the import map is enough. Self-contained HTML files covers that approach in general.
When it does not work
| What you see | Cause | Fix |
|---|---|---|
| Failed to resolve module specifier "three" | No import map, or it comes after the module script | Add the import map in the head, first |
| Cannot use import statement outside a module | The script tag has no type="module" |
Add type="module" |
| THREE is not defined | An old tutorial's three.min.js, removed in r161 |
Use the import map and three.module.js |
| The same error names an addon path | The map has no three/addons/ entry |
Add it with the same version |
| A black shape | A lit material and no light | Add lights, or use MeshBasicMaterial |
| An empty scene, no error | The camera is inside the object, or render never runs |
Move the camera back and start the draw loop |
| A stretched shape | camera.aspect not updated after a resize |
Set it, then updateProjectionMatrix() |
| Soft, blurry edges | No pixel ratio set | setPixelRatio(devicePixelRatio) |
| main.js blocked by CORS | A local module file opened from disk | Keep the code inline, or use a local server |
For errors outside three.js, HTML JavaScript not working walks through the console checks.
Share it as a link
A 3D scene is hard to show in a screenshot: the point is turning it yourself. An .html attachment may open as plain code on a phone, or not at all.
To send the working version, paste the page into a NOS document and choose Create share link. HTML to link walks through it.
We saved this viewer in the NOS workspace and checked its canvas and colour control. The example loads three.js from cdn.jsdelivr.net and builds its shapes and floor texture in the page.

Open the viewer’s actual share link.
The NOS sandbox restricts external image and data requests. Use an allowed upload route or embedded assets instead of assuming a model URL will load. The CDN-based example still needs an internet connection. After editing the code, save it and reopen the same reader link to check the new version.