Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 39 ยท Animation and Interaction

Raycasting and Picking Objects in Three.js

Pick 3D objects with the mouse in Three.js using Raycaster: normalized device coordinates, hover and click, intersection data, layers, dragging on a plane and line of sight.

The page gives you a 2D mouse position, but your world is 3D. How do you know which object the user clicked? The standard answer is raycasting: imagine shooting an invisible laser from the camera through the pixel under the pointer. The first object the laser hits is the one the user meant. Three.js packages this in the Raycaster class.

Raycasting powers hover effects, clicking products, selecting units, placing furniture, drag and drop, and non-mouse jobs like "is there a wall between these two characters?". In this lesson you will convert pointer positions, read intersection results, drag objects across a floor and use rays for game logic.

From pixels to a ray

A raycaster needs an origin and a direction. For mouse picking, you describe the pointer in normalized device coordinates (NDC): x and y each run from -1 to 1, with (0, 0) at the center of the canvas and y pointing up (the opposite of the page's y). Then setFromCamera builds the ray for you, taking perspective into account.

JavaScript
const raycaster = new THREE.Raycaster();
const pointer = new THREE.Vector2();

canvas.addEventListener('pointermove', (event) => {
  const rect = canvas.getBoundingClientRect();
  pointer.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
  pointer.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
});

// later, in the loop:
raycaster.setFromCamera(pointer, camera);
const hits = raycaster.intersectObjects(scene.children, false);
if (hits.length) console.log(hits[0].object.name);

Always measure with getBoundingClientRect of the canvas, not window.innerWidth, otherwise picking is off whenever the canvas is not full screen (a very common bug).

Picking step by step

Pointer Pixels from the event
NDC -1 to 1, y up
Ray setFromCamera
Hits Sorted, nearest first

intersectObjects returns every hit along the ray, closest first.

1 / 2

What an intersection contains

intersectObject(obj, recursive) and intersectObjects(array, recursive) return an array of hits sorted by distance. Each hit has:

Field Meaning
object The mesh that was hit
distance From the ray origin to the hit
point Hit position in world space (Vector3)
face, faceIndex The triangle hit (with its normal, in object space)
uv Texture coordinate at the hit; click a texture to paint it
instanceId For InstancedMesh, which instance

Pass recursive = true (the default for intersectObject) to test children as well; for glTF models where meshes are nested inside groups, you almost always want it. Lines and points are only hit within raycaster.params.Line.threshold and raycaster.params.Points.threshold, which you often need to raise.

The raycaster uses each object's matrixWorld, which renderer.render() refreshes. If you raycast before the first render, call scene.updateMatrixWorld() yourself.

Hover and click

The next example highlights the cube under the pointer and toggles a selected state on click. In the console, a ray aimed at the second cube is tested first so that you can see the numbers without touching the mouse.

Hover highlight and click to select

Move the pointer over a cube and click it. Casting every frame is fine for a handful of objects. For large scenes, cast only when the pointer actually moved, and only against the objects that can be picked.

Layers and filtering

Each object belongs to numbered layers (0 to 31). A camera renders objects on the layers it has enabled, and a raycaster tests objects on its own enabled layers:

JavaScript
pickable.layers.set(1);               // only layer 1
raycaster.layers.set(1);              // the ray ignores everything else
camera.layers.enable(1);              // keep rendering it

This is the clean way to say "the floor is not clickable", "ignore invisible trigger volumes" or "only the labels are interactive". Alternatively, build an array of pickable objects and pass only that array to intersectObjects. Objects with visible = false are still raycast unless you filter them, because the raycaster looks at geometry, not at whether it would be drawn.

Dragging along a floor

Often the click is not the end of the story: the user drags the object. A mouse position corresponds to a whole ray, not a point, so you need one more constraint. Dragging on a floor means "intersect the ray with an infinite horizontal plane". Ray.intersectPlane does it with pure math and no meshes involved.

Drag cubes on the ground plane

The offset vector stores where on the cube you grabbed it; without it the cube would jump so its center sits under the cursor. setPointerCapture keeps pointermove events flowing even when the cursor leaves the canvas mid-drag. For real drag-and-drop with snapping, rotation handles and gizmos, DragControls and TransformControls from the add-ons build on these ideas (see controls).

Rays are not only for the mouse

A Raycaster can be built from any origin and direction: new THREE.Raycaster(origin, direction, near, far). Typical game uses:

  • Ground detection: cast downward from a character to find the floor height and the surface normal.
  • Line of sight: cast from the enemy toward the player and check whether the first hit is the player or a wall.
  • Laser, bullet or tool aim: cast along the camera's forward direction (camera.getWorldDirection(vec)).
  • Collision avoidance: short rays in several directions detect nearby walls.
JavaScript
const ray = new THREE.Raycaster(enemy.position, toPlayer.normalize(), 0, 20);
const seen = ray.intersectObjects(obstaclesAndPlayer)[0]?.object === player;

Performance notes

  • Raycasting tests every triangle of a mesh (after a bounding-sphere check). A model with a million triangles is slow to pick against. Raycast a simplified invisible proxy mesh, or use the three-mesh-bvh library, which accelerates raycasts with a spatial tree.
  • InstancedMesh supports raycasting and reports instanceId.
  • Sprite and Points have their own rules; Sprite uses its screen-facing quad, Points uses the threshold mentioned above.
  • GPU picking (render object ids to an offscreen texture and read one pixel) is the alternative for scenes with millions of triangles; it is more work to set up.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which pointer coordinates does Raycaster.setFromCamera expect?

    NDC puts (0, 0) at the canvas center and flips y so that up is positive.
  2. 2. In what order does intersectObjects return hits?

    The results are sorted by distance from the ray origin, so hits[0] is the first object the ray meets.
  3. 3. Why use Ray.intersectPlane while dragging an object on the ground?

    A 2D pointer corresponds to a line of possible 3D points. Intersecting that ray with a floor plane picks one.
  4. 4. How can you make the raycaster ignore objects that are not clickable?

    Layers on the raycaster, or an explicit array of pickable meshes, restrict what can be hit.

Summary

  • A raycaster shoots a ray from the camera through the pointer (setFromCamera with NDC) and returns sorted intersections.
  • Convert pointer positions using the canvas's bounding rectangle, and remember y is flipped.
  • Hits carry object, point, distance, face, uv and instanceId.
  • Use layers or a pickable list, raycast simplified proxies for heavy models, and intersectPlane for dragging.
  • Rays are also tools for line of sight, ground detection and aiming.

Next: OrbitControls and Camera Rigs