Model Viewer

A 3D model viewer component with orbit controls and staging options.

vu-model-viewer · @velkin/react-pro/model-viewer

Copy page

Import

React

npm i @velkin/react-pro

import { LicenseInfo } from "@velkin/license";
// Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY
// Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY
LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? "");

// @velkin-pro
import { VuModelViewer } from "@velkin/react-pro/model-viewer";

Examples

API

Props

Prop	Type	Default	Description
src	`string`	""	Model source URL.
alt	`string`	"3D model"	Accessible description text.
poster	`null \| string`	null	Poster image URL shown before reveal.
reveal	VuModelViewerReveal	"auto"	Reveal mode for poster/model transition.
loading	VuModelViewerLoading	"auto"	Loading behavior hint.
cameraControls	`boolean`	true	Enables orbit controls.
cameraOrbit	`string`	"0deg 75deg 105%"	Camera orbit string (theta phi radius).
cameraTarget	`string`	"auto auto auto"	Camera target string.
autoRotate	`boolean`	false	Enables continuous auto-rotation.
pmiSrc	`string`	""	Sidecar PMI JSON source.
pmiVisible	`boolean`	true	Toggles PMI visibility.
loadingLabel	`string`	""	Override for loading poster / progress accessible copy.
interactionPromptLabel	`string`	""	Override for the orbit/zoom hint text.
fullscreenLabel	`string`	""	Override for enter-fullscreen accessible name.
exitFullscreenLabel	`string`	""	Override for exit-fullscreen accessible name.
showPmiLabel	`string`	""	Override for show-PMI button copy.
hidePmiLabel	`string`	""	Override for hide-PMI button copy.
unlimitedOrbit	`boolean`	false	When true, orbit has no angle limits so the model can rotate freely on all axes.
axesIndicator	VuModelViewerAxesIndicator	"none"	Show X/Y/Z axis lines in a corner for orientation reference. Use "none" to hide.
axesIndicatorSpace	VuModelViewerAxesSpace	"world"	`world` = screen-projected world axes; `model` = local axes after `heightAxis` (CAD / Z-up).
environment	`string`	""	HDR environment map URL (.hdr — loaded via RGBELoader).
skyboxImage	`string`	""	Equirectangular HDR for background (.hdr, loaded via RGBELoader).
disableContextMenu	`boolean`	false	When true, right-click context menu on the canvas is disabled.
withFullscreenButton	`boolean`	false	Shows a fullscreen toggle in the corner.
withPmiToggleButton	`boolean`	false	Shows a built-in PMI visibility toggle in the corner.
dracoDecoderPath	`string`	""	Optional DRACO decoder base path for compressed glTF.
ktx2TranscoderPath	`string`	""	Optional KTX2/Basis transcoder path for glTF textures.
texture	`string`	""	Comma-separated base-color map URLs mapped onto materials in order (cycles if fewer).
pmiWorldLeaderLength	`number`	40	Default leader length in model units for simple leaders (`leader.leader_points` not used).
pmiDefaultLineColor	`string`	"var(--vu-color-foreground)"	PMI line/arrow/datum color; supports `var(--token)` resolved via computed style.
pmiDefaultTextColor	`string`	""	PMI label fill when JSON omits `textColor`; empty uses the resolved line color.
pmiLabelOrientation	PmiLabelOrientation	"billboard"	PMI label orientation: `billboard` (face camera) or `plane` (annotation normal).
heightAxis	VuModelViewerHeightAxis	"z"	Model up axis: `y` (glTF/Blender) or `z` (CAD); `z` rotates so Z is vertical in the viewer.
format	VuModelViewerFormat	""	Explicit format (`gltf` \| `stl` \| `obj`) when URL/MIME sniffing is insufficient.
preserveCameraOnSrcChange	`boolean`	false	Keep orbit/target and interaction state when `src` changes instead of reframing.

Events

Event	Detail	Description
vu-load	Event	Fired when the model has finished loading.
vu-error	VuModelViewerErrorDetail	Fired when model loading fails.
vu-progress	VuModelViewerProgressDetail	Fired during model loading.
vu-camera	VuModelViewerCameraChangeDetail	Fired when camera orbit or target changes.
vu-poster	VuModelViewerPosterDetail	Fired when the poster is hidden and the model is revealed.
vu-visibility	VuModelViewerModelVisibilityDetail	Fired when model visibility changes.
vu-pmi	VuModelViewerPmiVisibilityChangeDetail	Fired when PMI visibility is toggled.

Slots

Slot	Description
poster	Content shown while the model is loading (e.g. placeholder image or spinner).

CSS parts

Part	Description
container	Wrapper around the canvas and chrome overlays.
poster	Loading/poster overlay.
interaction-prompt	Orbit/zoom interaction hint.
progress	Determinate load progress bar.
fullscreen-button	Fullscreen toggle control.
pmi-toggle-button	PMI visibility toggle control.

Methods

Method	Description
resetView	Restores default camera orbit/target and reapplies camera transforms.

Types

Name	Definition
PmiLabelOrientation	`"billboard" \| "plane"`
string \| null	`null \| string`
VuModelViewerAxesIndicator	`"none" \| "top-right" \| "top-left" \| "bottom-right" \| "bottom-left"`
VuModelViewerAxesSpace	`"world" \| "model"`
VuModelViewerCameraChangeDetail	`{ source: string; }`
VuModelViewerErrorDetail	`unknown`
VuModelViewerFormat	`"" \| "gltf" \| "stl" \| "obj"`
VuModelViewerHeightAxis	`"y" \| "z"`
VuModelViewerLoading	`"auto" \| "lazy" \| "eager"`
VuModelViewerModelVisibilityDetail	`{ visible: boolean; }`
VuModelViewerPmiVisibilityChangeDetail	`{ visible: boolean; }`
VuModelViewerPosterDetail	`{ dismissed: true; }`
VuModelViewerProgressDetail	`{ totalProgress: number; reason?: string; }`
VuModelViewerReveal	`"auto" \| "manual"`

Import

React

npm i @velkin/react-pro import { LicenseInfo } from "@velkin/license"; // Vite: import.meta.env.VITE_VELKIN_LICENSE_KEY // Next: process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY LicenseInfo.setLicenseKey(import.meta.env.VITE_VELKIN_LICENSE_KEY ?? process.env.NEXT_PUBLIC_VELKIN_LICENSE_KEY ?? ""); // @velkin-pro import { VuModelViewer } from "@velkin/react-pro/model-viewer";

API

Props

Prop	Type	Default	Description
src	`string`	""	Model source URL.
alt	`string`	"3D model"	Accessible description text.
poster	`null \| string`	null	Poster image URL shown before reveal.
reveal	VuModelViewerReveal	"auto"	Reveal mode for poster/model transition.
loading	VuModelViewerLoading	"auto"	Loading behavior hint.
cameraControls	`boolean`	true	Enables orbit controls.
cameraOrbit	`string`	"0deg 75deg 105%"	Camera orbit string (theta phi radius).
cameraTarget	`string`	"auto auto auto"	Camera target string.
autoRotate	`boolean`	false	Enables continuous auto-rotation.
pmiSrc	`string`	""	Sidecar PMI JSON source.
pmiVisible	`boolean`	true	Toggles PMI visibility.
loadingLabel	`string`	""	Override for loading poster / progress accessible copy.
interactionPromptLabel	`string`	""	Override for the orbit/zoom hint text.
fullscreenLabel	`string`	""	Override for enter-fullscreen accessible name.
exitFullscreenLabel	`string`	""	Override for exit-fullscreen accessible name.
showPmiLabel	`string`	""	Override for show-PMI button copy.
hidePmiLabel	`string`	""	Override for hide-PMI button copy.
unlimitedOrbit	`boolean`	false	When true, orbit has no angle limits so the model can rotate freely on all axes.
axesIndicator	VuModelViewerAxesIndicator	"none"	Show X/Y/Z axis lines in a corner for orientation reference. Use "none" to hide.
axesIndicatorSpace	VuModelViewerAxesSpace	"world"	`world` = screen-projected world axes; `model` = local axes after `heightAxis` (CAD / Z-up).
environment	`string`	""	HDR environment map URL (.hdr — loaded via RGBELoader).
skyboxImage	`string`	""	Equirectangular HDR for background (.hdr, loaded via RGBELoader).
disableContextMenu	`boolean`	false	When true, right-click context menu on the canvas is disabled.
withFullscreenButton	`boolean`	false	Shows a fullscreen toggle in the corner.
withPmiToggleButton	`boolean`	false	Shows a built-in PMI visibility toggle in the corner.
dracoDecoderPath	`string`	""	Optional DRACO decoder base path for compressed glTF.
ktx2TranscoderPath	`string`	""	Optional KTX2/Basis transcoder path for glTF textures.
texture	`string`	""	Comma-separated base-color map URLs mapped onto materials in order (cycles if fewer).
pmiWorldLeaderLength	`number`	40	Default leader length in model units for simple leaders (`leader.leader_points` not used).
pmiDefaultLineColor	`string`	"var(--vu-color-foreground)"	PMI line/arrow/datum color; supports `var(--token)` resolved via computed style.
pmiDefaultTextColor	`string`	""	PMI label fill when JSON omits `textColor`; empty uses the resolved line color.
pmiLabelOrientation	PmiLabelOrientation	"billboard"	PMI label orientation: `billboard` (face camera) or `plane` (annotation normal).
heightAxis	VuModelViewerHeightAxis	"z"	Model up axis: `y` (glTF/Blender) or `z` (CAD); `z` rotates so Z is vertical in the viewer.
format	VuModelViewerFormat	""	Explicit format (`gltf` \| `stl` \| `obj`) when URL/MIME sniffing is insufficient.
preserveCameraOnSrcChange	`boolean`	false	Keep orbit/target and interaction state when `src` changes instead of reframing.

Events

Event	Detail	Description
vu-load	Event	Fired when the model has finished loading.
vu-error	VuModelViewerErrorDetail	Fired when model loading fails.
vu-progress	VuModelViewerProgressDetail	Fired during model loading.
vu-camera	VuModelViewerCameraChangeDetail	Fired when camera orbit or target changes.
vu-poster	VuModelViewerPosterDetail	Fired when the poster is hidden and the model is revealed.
vu-visibility	VuModelViewerModelVisibilityDetail	Fired when model visibility changes.
vu-pmi	VuModelViewerPmiVisibilityChangeDetail	Fired when PMI visibility is toggled.

Slots

Slot	Description
poster	Content shown while the model is loading (e.g. placeholder image or spinner).

CSS parts

Part	Description
container	Wrapper around the canvas and chrome overlays.
poster	Loading/poster overlay.
interaction-prompt	Orbit/zoom interaction hint.
progress	Determinate load progress bar.
fullscreen-button	Fullscreen toggle control.
pmi-toggle-button	PMI visibility toggle control.

Methods

Method	Description
resetView	Restores default camera orbit/target and reapplies camera transforms.

Types

Name	Definition
PmiLabelOrientation	`"billboard" \| "plane"`
string \| null	`null \| string`
VuModelViewerAxesIndicator	`"none" \| "top-right" \| "top-left" \| "bottom-right" \| "bottom-left"`
VuModelViewerAxesSpace	`"world" \| "model"`
VuModelViewerCameraChangeDetail	`{ source: string; }`
VuModelViewerErrorDetail	`unknown`
VuModelViewerFormat	`"" \| "gltf" \| "stl" \| "obj"`
VuModelViewerHeightAxis	`"y" \| "z"`
VuModelViewerLoading	`"auto" \| "lazy" \| "eager"`
VuModelViewerModelVisibilityDetail	`{ visible: boolean; }`
VuModelViewerPmiVisibilityChangeDetail	`{ visible: boolean; }`
VuModelViewerPosterDetail	`{ dismissed: true; }`
VuModelViewerProgressDetail	`{ totalProgress: number; reason?: string; }`
VuModelViewerReveal	`"auto" \| "manual"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Data display

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Data display

Guides

Browse