@3driseai/3drise-viewer

React components for embedding 3dRise scenes in your app.

You build in the 3dRise studio — create objects, apply materials, set up animations, effects and interactions — then render the result in React with one component. Nothing about the scene is configured in code: geometry, materials, lighting, animations and interactions all come from what you published.

There are many components, these are the main ones:

| Component | Embeds | | ------------------ | ----------------------------------------------------------------------- | | <ProjectLoader /> | A whole project — scene, camera, lights, environment, animations, cursors. Renders its own canvas. | | <ObjectNodeApi /> | A single object (and its children) from the studio, dropped into a canvas you control. |

A ready to go react project with some examples: https://github.com/nadavtal/3drise-react

Installation

npm install @3driseai/3drise-viewer

The package ships as ESM only with bundled TypeScript declarations.

Peer dependencies

| Peer dependency | Version | | --------------------- | --------------- | | react | ^18 or ^19 | | three | ^0.170 | | @react-three/fiber | ^9 | | @react-three/drei | ^10 | | @react-three/rapier | ^2 | | @gsap/react | ^2.1.2 |

npm 7+ and pnpm 8+ install these for you. On Yarn — classic or Berry — you'll need to add them yourself.

three must resolve to a single copy. Two versions of three.js in one app is the classic React Three Fiber failure — objects silently refuse to render, instanceof checks fail. If your app pins a different three than the ^0.170 declared here, dedupe it (npm ls three to check, overrides / resolutions to force one version) rather than letting both install.

Embed a whole project

ProjectLoader fetches a published project by id, renders its own <Canvas>, and shows a loading indicator until the scene is ready. This is the whole integration:

import { ProjectLoader } from '@3driseai/3drise-viewer';

export default function ProjectPage({ projectId }: { projectId: string }) {
  return (
    <div style={{ height: '100svh', position: 'relative' }}>
      <ProjectLoader projectId={projectId} />
    </div>
  );
}

ProjectLoader renders a <Canvas> internally, so it needs a sized parent — give the wrapper an explicit height (100svh, 100% of a sized container, a fixed pixel value) or nothing will be visible.

Reacting to the scene

Every callback is optional:

import { ProjectLoader } from '@3driseai/3drise-viewer';
import type { CreatedObjectSettings } from '@3driseai/3drise-core';
import type { Object3D } from 'three';

<ProjectLoader
  projectId={projectId}
  loadingIndicator={<MySpinner />}
  onSceneInitialized={() => setReady(true)}
  onObjectClick={(object: CreatedObjectSettings, ref: Object3D) => {
    openInspector(object.meshSettings.name, ref);
  }}
  onObjectHover={(object, ref) => setHovered(object.id)}
/>;

<ProjectLoader /> props

| Prop | Type | Description | | -------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | projectId | string (required) | Id of the published 3dRise project to load. | | loadingIndicator | React.ReactNode | Replaces the built-in full-screen loader shown while the project is fetched. | | onSceneInitialized | () => void | Fires once the scene has mounted. | | onObjectClick | (object: CreatedObjectSettings, ref: Object3D, event: ThreeEvent<MouseEvent>) => void | A scene object was clicked. | | onObjectHover | (object: CreatedObjectSettings, ref: Object3D) => void | Pointer entered a scene object. | | onElementClick | (element: HtmlElement) => void | A 2D UI element in the project was clicked. | | onElementHover | (element: HtmlElement \| null) => void | Pointer entered/left a 2D UI element. | | onObjectReady | (object, ref: Object3D) => void | Every object in the scene reports its Object3D here — see below. | | onObjectDispose | (object, ref: Object3D) => void | The matching teardown event for onObjectReady. |

Embed a single object

Sometimes you don't want a whole scene — you want one thing you built in the studio, placed in a canvas your app already owns.

Create the object in the 3dRise studio, give it its material, animations, effects and click interactions, publish it, and copy its object id. ObjectNodeApi fetches that object's tree and renders it — with everything you configured intact:

import { Canvas } from '@react-three/fiber';
import { OrbitControls } from '@react-three/drei';
import { ObjectNodeApi } from '@3driseai/3drise-viewer';
import type { CameraState } from '@3driseai/3drise-core';

const cameraSettings: CameraState = {
  position: [0, 2, 8],
  orientation: [0, 0, 0, 1],
  fov: 50,
  near: 0.1,
  far: 1000,
  animations: [],
  mouseMove: { enabled: false, properties: [] },
  controls: { enabled: true, target: [0, 0, 0] },
};

export function Hero({ objectId }: { objectId: string }) {
  return (
    <Canvas camera={{ position: [0, 2, 8], fov: 50 }} style={{ height: '60vh' }}>
      <ambientLight intensity={0.5} />
      <directionalLight position={[5, 10, 5]} intensity={1.5} />

      <ObjectNodeApi objectId={objectId} />

      <OrbitControls />
    </Canvas>
  );
}

Because you own the canvas here, you also own everything around the object — camera, lighting, controls and background are yours to provide. ObjectNodeApi contributes only the object itself, so an object with no emissive material in an unlit canvas will render black. It renders null until the fetch resolves, so it's safe to mount immediately.

Groups come through whole: if the object has children in the studio, they're rendered as a tree with their own materials and animations.

<ObjectNodeApi /> props

| Prop | Type | Description | | ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | objectId | string (required) | Id of the published scene object to load. | | handleObjectClick | (object: CreatedObjectSettings, ref: Object3D, event: ThreeEvent<MouseEvent>) => void | The object was clicked. Note the name differs from ProjectLoader's onObjectClick. | | onObjectReady | (object, ref: Object3D) => void | The object reports its Object3D here — see below. | | onObjectDispose | (object, ref: Object3D) => void | The matching teardown event. |

Getting at the three.js objects

Both components implement the same two props, so you can build a live registry of what's in the scene without reaching into refs yourself:

type OnObjectReady   = (object: ObjectReadySource, ref: Object3D) => void;
type OnObjectDispose = (object: ObjectReadySource, ref: Object3D) => void;

• object is the settings the object was built with in the studio. It's a union: scene objects give you a CreatedObjectSettings (with its studio id and meshSettings), while effects and cursors give you their own config — narrow it before reading fields. Never null.
• ref is the root Object3D that just mounted.
• Every onObjectReady is eventually paired with an onObjectDispose for the same ref, on unmount or when the component swaps its root — so a Map built from these events stays accurate.

const objects = useRef(new Map<string, Object3D>());

<ProjectLoader
  projectId={projectId}
  onObjectReady={(object, ref) => objects.current.set(ref.uuid, ref)}
  onObjectDispose={(object, ref) => objects.current.delete(ref.uuid)}
/>;

To key by the studio id instead, narrow first — if ('meshSettings' in object) tells you it's a CreatedObjectSettings.

From there it's plain three.js — animate it, raycast against it, attach it to your own logic.

TypeScript

Types ship with the package:

import type {
  ObjectReadyProps,
  ObjectReadySource,
  OnObjectReady,
  OnObjectDispose,
} from '@3driseai/3drise-viewer';

Scene and object types come from the core package, which installs alongside this one:

import type { CameraState, CreatedObjectSettings } from '@3driseai/3drise-core';

Notes

• ESM only. There is no CommonJS build. In Next.js or another SSR framework, render the viewer client-side ('use client', or a dynamic import with ssr: false) — it touches window and WebGL.
• One entry point. Import everything from @3driseai/3drise-viewer; there are no deep subpath imports.

Links

• 3dRise