Using Popmelt with Three.js and react-three-fiber

Core can target objects in Three.js scenes through its React Three Fiber integration. The adapter registers the scene, camera, and renderer with Core, so scene objects use the familiar hover, annotation, and thread workflow. It does not depend on See or object segmentation.

This guide covers React Three Fiber, not automatic integration with an arbitrary Three.js canvas. For images and paused video, see Creating annotations with the Chat tool.

React Three Fiber

Install the scene peers alongside Core:

npm install @popmelt.com/core @react-three/fiber three

Keep the provider outside the canvas and the adapter inside it:

import { PopmeltProvider } from '@popmelt.com/core';
import { PopmeltThreeAdapter } from '@popmelt.com/core/react-three-fiber';
import { Canvas } from '@react-three/fiber';

export function ProductPreview() {
  return (
    <PopmeltProvider>
      <Canvas>
        <PopmeltThreeAdapter />
        <ProductScene />
      </Canvas>
    </PopmeltProvider>
  );
}

ProductScene is your scene component. Named scene objects receive readable labels. Add stable application identity when names or ordering may change:

<mesh
  name="Bottle"
  userData={{ popmeltId: 'hero-bottle', popmeltLabel: 'Hero bottle' }}
>
  {/* Your geometry and material */}
</mesh>

Leave scene feedback

Choose Chat (C), point to a scene object, and leave feedback. The adapter targets scene objects rather than treating the canvas as a single DOM element. Send the pending work with Command/Control+Enter, then review and refine it in the thread.

For example: “Make the bottle material less reflective without changing the lighting.”

Adapt the scene's semantics

Use distinct adapter IDs for multiple canvases. Pass root to restrict targeting to a scene subtree or captureFrame={false} to omit renderer screenshots. The select, key, label, and describe options let you map scene objects to the application's own semantics.

The Core README covers those options and the adapter hook for advanced composition.