Skip to content
awesome-tour

Type to search every page.

    Ereact-three-fiberContents

    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.

    Terminal window
    pnpm add @awesome-tour/three @react-three/fiber three
    import { 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.Content positions against a 3D target is updated every animation frame. So is the overlay, through useTargetRect.
    • 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 like OrbitControls work again.
    • Steps without a shot leave the camera where it is.
    • With controls, the controls’ target follows lookAt, and update() 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.