@reflct/react

Overview

A React library for integrating Reflct 3D scenes into your React apps.

Visit Reflct.app for more information.

To install the package, run:

# Install the package
npm install @reflct/react

or if you’re using yarn:

# Install the package
yarn add @reflct/react

Getting Started

Here’s a basic example of how to use the Viewer component:

import React from "react";
import { Viewer } from "@reflct/react";
 
const Page = () => {
  return <Viewer id={"your-scene-id"} apikey={"your-apikey"} />;
};
 
export default Page;

Advanced Usage

The Viewer component includes props for listening to events and customizing the UI:

<Viewer
  id={"your-scene-id"}
  apikey={"your-apikey"}
  isPreview={true}
  className={"your-class-name"}
  transitionSpeedMultiplier={1.0}
  automodeTransitionSpeedMultiplier={0.5}
  // Event handlers
  onLoadStart={() => {}}
  onLoadProgressUpdate={(progress) => {}}
  onLoadComplete={(viewGroups, global) => {}}
  onStateChangeStart={(targetView, targetViewGroup, global) => {}}
  onStateChangeComplete={(currentView, currentViewGroup, global) => {}}
  onError={(error) => {}}
/>

Props

Prop	Type	Description
`id`	string	The unique ID of your scene
`apikey`	string	Your API key
`isPreview`	boolean	Use a preview version of the scene
`sceneRevealMode`	string	The mode to reveal the scene. ‘gradual’ or ‘instant’
`sharedMemoryForWorkers`	boolean	Use shared memory for workers
`className`	string	Custom CSS class for the viewer
`transitionSpeedMultiplier`	number	Speed multiplier for camera transitions (default: 1)
`automodeTransitionSpeedMultiplier`	number	Speed multiplier for camera transitions in automode (default: 0.5)

Events

Event	Type	Description
`onLoadStart`	`() => void`	Triggered when the scene starts loading
`onLoadProgressUpdate`	`(progress: number) => void`	Updates as the scene loads
`onLoadComplete`	`(viewGroups, global, camera) => void`	Triggered when the scene is fully loaded
`onStateChangeStart`	`(targetView, targetViewGroup, global, camera) => void`	Triggered at the start of a state change
`onStateChangeComplete`	`(currentView, currentViewGroup, global, camera) => void`	Triggered when a state change is complete
`onError`	`(error: string) => void`	Triggered when an error occurs

Example: Using Events and Metadata

You can use metadata from events to update your application logic, such as state or UI:

import React from "react";
import { Viewer } from "@reflct/react";
import useProductStore from "../stores/product-store";
 
const Page = () => {
  const extractMetadata = (viewGroups, global, key) => {
    return (
      viewGroups[0].views[0].metadata?.[key] ||
      viewGroups[0].metadata?.[key] ||
      global.metadata?.[key]
    );
  };
 
  return (
    <Viewer
      id={sceneId}
      apikey={apikey}
      onLoadComplete={(viewGroups, global) => {
        useProductStore.setState((state) => {
          state.loading = false;
          state.title = extractMetadata(viewGroups, global, "productTitle");
          state.subtitle = extractMetadata(
            viewGroups,
            global,
            "productCategory"
          );
          const price = extractMetadata(viewGroups, global, "price");
          state.price = !isNaN(Number(price)) ? Number(price) : null;
        });
      }}
    />
  );
};

Customizing the UI

You can pass children to customize the viewer’s UI:

<Viewer id={"your-scene-id"} apikey={"your-apikey"}>
  {({
    currentView,
    currentViewGroup,
    global,
    index,
    automode,
    setAutomode,
    isLoading,
    loadProgress,
    nextView,
    prevView,
    summaryImage,
    linkedScenes,
    loadScene,
  }) => <div>Custom Controls</div>}
</Viewer>

Prop	Type	Description
`currentView`	CurrentViewMetadata	Metadata for the current view
`currentViewGroup`	ViewGroupMetadata	Metadata for the current view group
`global`	GlobalMetadata	Global scene metadata
`index`	number	Current view index
`automode`	boolean	Is auto mode enabled?
`setAutomode`	function	Function to toggle auto mode
`isLoading`	boolean	Is the scene loading?
`loadProgress`	number	The progress of the scene loading
`nextView`	function	Function to navigate to the next view
`prevView`	function	Function to navigate to the previous view
`summaryImage`	string or null	The summary image of the scene
`linkedScenes`	array	The linked scenes of the scene
`loadScene`	function	The function to load linked scene

If you wish to customise the UI of the hitpoints, you can do that by giving the hitPoint prop.

<Viewer
  id={"your-scene-id"}
  apikey={"your-apikey"}
  hitPoint={(state: {
    index: number,
    isSelected: boolean,
    inCurrentGroup: boolean,
    select: () => void,
  }) => <button onClick={state.select}>Hitpoint</button>}
/>

Props	Type	Description
index	number	The index of the hitpoint
isSelected	boolean	Whether the hitpoint is selected
inCurrentGroup	boolean	Whether the hitpoint is in the current view group
select	function (() => void)	The function to select the hitpoint

Linking scenes Optimizing 3DGS for Web