react-three-fiber
Highlight objects inside a react-three-fiber scene and fly the camera per step.
@awesome-tour/three turns 3D objects into tour targets. Each object is registered as a virtual element: its world-space bounding box is projected onto the screen whenever the tour asks for its rect. The regular DOM overlay and popover therefore follow the object as the camera moves. See the 3D guide.
pnpm add @awesome-tour/three @react-three/fiber threeimport { anchor } from '@awesome-tour/react';import { TourTarget3D, useTourCamera } from '@awesome-tour/three';
const steps = [{ id: 'engine', target: anchor('engine'), title: 'The engine' }];
<Canvas> <TourTarget3D name="engine"> <Engine /> </TourTarget3D> <CameraRig /></Canvas>;TourTarget3D
Registers a 3D object as a named anchor. Reference it from a step with anchor(name). Must be rendered inside a react-three-fiber Canvas.
| Prop | Type | Default | Description |
|---|---|---|---|
name |
string |
— | Anchor id. |
object |
RefObject<Object3D | null> |
— | Object to highlight. When omitted, the children are wrapped in a group and that group is highlighted. |
children |
ReactNode |
— | Scene content to highlight. |
registry |
AnchorRegistry |
the provider’s, else the global one | Registry to register into. |
// Highlight an existing object instead of wrapping children:const wheel = React.useRef<Mesh>(null);<mesh ref={wheel}>…</mesh><TourTarget3D name="wheel" object={wheel} />Notes:
- The virtual element uses the canvas as its
contextElement, so scrolling and scroll-into-view work relative to the canvas. - Content that
Tour.Contentpositions against a 3D target is updated every animation frame. So is the overlay, throughuseTargetRect. - When the object is entirely behind the camera, it projects to an empty off-screen rect.
useTourCamera
function useTourCamera( shots: Partial<Record<string, { position: [x, y, z]; lookAt?: [x, y, z] }>>, options?: { tour?: TourInstance; // default: the nearest Tour.Root's smoothing?: number; // damping factor, higher = faster. Default: 4 controls?: RefObject<{ target: Vector3; update(): void } | null>; },): void;Flies the camera to a shot for each step id while the tour is active. Call it from a component inside the Canvas.
- The motion is damped frame by frame (
MathUtils.damp). Once the camera has settled, it stops animating, so user controls likeOrbitControlswork again. - Steps without a shot leave the camera where it is.
- With
controls, the controls’targetfollowslookAt, andupdate()is called on every frame.
function CameraRig() { const controls = React.useRef(null); useTourCamera( { engine: { position: [3, 2, 4], lookAt: [0, 0.5, 0] }, wheel: { position: [-2, 1, 3], lookAt: [-1, 0, 0] }, }, { controls, smoothing: 3 }, ); return <OrbitControls ref={controls} />;}The hook needs a tour. Render it inside Tour.Root (the Canvas content is part of the same React tree), or pass options.tour. Outside a tour it does nothing.
projectObjectToRect
function projectObjectToRect(object: Object3D, camera: Camera, canvas: HTMLElement): RectLike;Projects the corners of an object’s world bounding box to a viewport rect in CSS pixels, ignoring corners behind the camera. An object with an empty bounding box, such as a group with no geometry, uses its world position instead. Use it to build your own virtual targets, for example with createVirtualTarget or a getBoundingClientRect wrapper.