Splat Viewer - PlayCanvas React

Splat Viewer beta

A responsive and composable component for displaying Gaussian splats.

Includes built-in camera controls, loading states, and optional UI slots for overlays or actions.
Supports large assets with lazy loading and automatic framing. Use it in modals, pages, or full-screen scenes.

Supports compressed gaussian splats.

Open in

index.tsx


import { Viewer } from '@playcanvas/blocks';
 
export function SplatViewerDemo() {
  return (
    <Viewer.Splat src={splatUrl} variant="paris" >
      <Viewer.Progress />
      <Viewer.Controls >
        <div className="flex gap-2 flex-grow">
            <Viewer.FullScreenButton />
            <Viewer.DownloadButton />
        </div>
        <div className="pointer-events-auto">
          <Viewer.CameraModeToggle />
          <Viewer.MenuButton />
        </div>
      </Viewer.Controls>
    </Viewer.Splat>
  )
}

Features

Orbit and fly controls.

Keyboard and mouse controls.

Controlled and uncontrolled mode.

Installable AI IDE rules (rules.mdc).

Suspenseful loading.

Camera animations. (coming soon)

Way points. (coming soon)

Version 0.1.1

View Source

Report an Issue

Installation

Manual

Follow the instructions on the Blocks page to install the component.


npm install @playcanvas/blocks

Install Tailwind and add the following to your index.css.


@import "@playcanvas/blocks";
@source "../node_modules/@playcanvas/blocks";

Anatomy

Import all parts and piece them together.


import { Viewer } from "@/components/ui/splat-viewer/";
 
export default () => (
  <Viewer.Splat src={splatUrl} >
    <Viewer.Controls >
      <Viewer.FullScreenButton />
      <Viewer.DownloadButton />
      <Viewer.CameraModeToggle />
      <Viewer.MenuButton />
      <Viewer.Progress />
    </Viewer.Controls>
  </Viewer.Viewer>
)

API Reference

Splat

A responsive and composable component for displaying Gaussian splats.

Name	Type	Default
`mode`	`CameraMode` The type of camera controls to use. `orbit`: An orbit camera that follows the splat. `fly`: A fly camera that follows the splat.	`'orbit'`
`defaultMode`	`CameraMode` The default mode of the camera.	`'orbit'`
`src`	`string \| Record<string, unknown>` The url of an image to display whilst the asset is loading.
`variant`	`Record<string, unknown> \| "paris" \| "neutral" \| "noir" \| "none"` The style of the camera to use. `paris`: A warm saturated style. `neutral`: A neutral style. `noir`: A black/white style.	`'neutral'`
`track`	`AnimationTrack` The track to use for the animation
`autoPlay`	`boolean` Whether to automatically play the animation	`false`
`onTypeChange`	`(type: "orbit" \| "fly") => void` A callback function for when the type of camera changes
`onAssetProgress`	`(progress: number) => void` A callback function for when the asset progress changes
`poster`	`string` The url of the poster image
`className`	`string` The className of the container
`children`	`React.ReactNode` The children of the component

useAssetViewer

A hook that provides the context for the asset viewer. This is handy if you need an imperative handle for the viewer. Use this if you need to trigger a download, or toggle the fullscreen mode, or access the loading progress.

Name	Type	Default
`isFullscreen`	`boolean` Whether the viewer is in fullscreen mode.
`toggleFullscreen`	`() => void` Toggles the fullscreen mode.
`triggerDownload`	`() => void` Triggers a download of the asset.
`src`	`string \| Record<string, unknown>` The source of the asset.
`isInteracting`	`boolean` Whether the viewer is interacting with the asset.
`mode`	`CameraMode` The type of camera to use.
`setMode`	`(mode: CameraMode) => void` The type of camera to use.
`overlay`	`"help" \| "settings" \| null` The overlay to display.	`null`
`setOverlay`	`(overlay: "help" \| "settings" \| null) => void` Toggles the overlay.
`autoRotate`	`boolean` Whether the auto rotate is enabled.
`setAutoRotate`	`(autoRotate: boolean) => void` Toggles the auto rotate.
`subscribe`	`(fn: (progress: number) => void) => () => void` Subscribes to the asset progress.
`subscribeCameraReset`	`(fn: () => void) => () => void` Subscribes to the camera reset.
`resetCamera`	`() => void` Resets the camera.

Controls

A simple container for UI controls that creates a sensible layout and optionally auto hides when the user is interacting.

Name	Type	Default
`className`	`string` The className of the controls
`autoHide`	`boolean` When enabled, the controls will be hidden when the user is not interacting with the asset.	`false`
`children`	`React.ReactNode` The children of the controls

FullScreenButton

A button for entering and exiting full screen mode.

Name	Type	Default
`variant`	`"default" \| "outline" \| "ghost" \| "link"`

DownloadButton

A button for downloading the current scene.

Name	Type	Default
`variant`	`"default" \| "outline" \| "ghost" \| "link"`