Getting Started — React — Five SDK | Realsee Developer Platform

This tutorial uses @realsee/five directly inside React.

What you'll learn in this chapter

How to install and import the Five SDK in a React project.
How to mount and dispose Five SDK within a component using useRef and useEffect.
How to render a 3D space that adapts automatically to window size changes.

Prerequisites

Scaffold a React project quickly with Vite

npm create vite@9.1.1 my-react-app -- --template react
cd my-react-app
npm install

npm create vite@9.1.1 my-react-app -- --template react-ts
cd my-react-app
npm install

Install dependencies

npm install @realsee/five@6.8.9 three@0.117.1

Info

@realsee/five: the Five SDK rendering engine.
three@0.117.1: the graphics/math library Five SDK depends on. Use this exact version.

Render a 3D space

The following builds the minimal runnable example inside a React component: create a Five SDK instance, mount it to a container, load work.json, listen for window changes, and clean up when the component unmounts.

import { useEffect, useRef } from 'react'
import { Five, parseWork } from '@realsee/five'

const workURL = 'https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json'

export default function FiveCanvas() {
  const containerRef = useRef(null)
  const fiveRef = useRef(null)

  useEffect(() => {
    const five = new Five()
    fiveRef.current = five

    if (containerRef.current) {
      five.appendTo(containerRef.current)
    }

    const controller = new AbortController()
    fetch(workURL, { signal: controller.signal })
      .then((res) => res.json())
      .then((json) => five.load(parseWork(json)))
      .catch(() => {})

    const onResize = () => five.refresh()
    window.addEventListener('resize', onResize, false)

    return () => {
      controller.abort()
      window.removeEventListener('resize', onResize, false)
      fiveRef.current && fiveRef.current.dispose()
    }
  }, [])

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <div ref={containerRef} style={{ width: '100%', height: '100%', overflow: 'hidden' }} />
    </div>
  )
}

import FiveCanvas from './FiveCanvas'

export default function App() {
  return <FiveCanvas />
}

import { useEffect, useRef } from 'react'
import { Five, parseWork } from '@realsee/five'

const workURL = 'https://vr-public.realsee-cdn.cn/release/static/image/release/five/work-sample/07bdc58f413bc5494f05c7cbb5cbdce4/work.json'

export default function FiveCanvas() {
  const containerRef = useRef<HTMLDivElement | null>(null)
  const fiveRef = useRef<Five | null>(null)

  useEffect(() => {
    const five = new Five()
    fiveRef.current = five

    if (containerRef.current) {
      five.appendTo(containerRef.current)
    }

    const controller = new AbortController()
    fetch(workURL, { signal: controller.signal })
      .then((res) => res.json())
      .then((json) => five.load(parseWork(json)))
      .catch(() => {})

    const onResize = () => five.refresh()
    window.addEventListener('resize', onResize, false)

    return () => {
      controller.abort()
      window.removeEventListener('resize', onResize, false)
      fiveRef.current?.dispose()
    }
  }, [])

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <div ref={containerRef} style={{ width: '100%', height: '100%', overflow: 'hidden' }} />
    </div>
  )
}

import FiveCanvas from './FiveCanvas'

export default function App() {
  return <FiveCanvas />
}

Start the development server:

npm run dev

Open your browser and confirm that the 3D space renders successfully. If you want to learn more about concepts such as work.json, parseWork(json), and five.load(work), continue to the next chapter.