Model Viewer 3D

ProNew

An interactive glTF model viewer with orbit controls, procedural studio lighting and a contact shadow, or a built-in shape.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.


pnpm dlx shadcn@latest add @tealmac-pro/model-viewer-3d

Prop	Type	Default	Description
`src`	`string`	`-`	URL of a glTF or GLB model. If it fails to load, `primitive` is shown.
`primitive`	`"torus-knot" \| "icosahedron" \| "box" \| "sphere" \| "torus"`	`"torus-knot"`	Built-in shape shown when there is no `src`.
`color`	`string`	theme	Colour of the built-in shape. Defaults to `--primary`.
`autoRotate`	`boolean`	`true`	Turn the camera slowly around the model.
`autoRotateSpeed`	`number`	`1.2`	Auto-rotate speed.
`zoom`	`boolean`	`false`	Allow wheel and pinch zoom. Off so the page keeps scrolling.
`shadows`	`boolean`	`true`	Soft contact shadow under the model.
`environment`	`"studio" \| "sunset" \| "night"`	`"studio"`	Procedural lighting preset; it makes no network request.
`label`	`string`	`"Interactive 3D model"`	Accessible description.
`onError`	`(error: unknown) => void`	`-`	Called when `src` fails to load.
`fallback`	`ReactNode`	gradient	Static frame shown while loading and when WebGL is unavailable.
`className`	`string`	`-`	Classes for the outer element.

Models are fitted to the view automatically. Draco-compressed models fetch their decoder from a CDN on first use.

three.js loads only when the component comes within 200px of the viewport, in its own chunk, so pages that do not show it never download it.
Rendering pauses while it is offscreen or the tab is hidden, and the pixel ratio is capped at 2.
With prefers-reduced-motion: reduce it renders a single still frame.
Without WebGL, or before the scene loads, a static gradient is shown instead.
Colours come from your theme's CSS variables and update when the theme changes.

Guide and examples


pnpm dlx shadcn@latest add @tealmac-pro/model-viewer-3d

Prop	Type	Default	Description
`src`	`string`	`-`	URL of a glTF or GLB model. If it fails to load, `primitive` is shown.
`primitive`	`"torus-knot" \| "icosahedron" \| "box" \| "sphere" \| "torus"`	`"torus-knot"`	Built-in shape shown when there is no `src`.
`color`	`string`	theme	Colour of the built-in shape. Defaults to `--primary`.
`autoRotate`	`boolean`	`true`	Turn the camera slowly around the model.
`autoRotateSpeed`	`number`	`1.2`	Auto-rotate speed.
`zoom`	`boolean`	`false`	Allow wheel and pinch zoom. Off so the page keeps scrolling.
`shadows`	`boolean`	`true`	Soft contact shadow under the model.
`environment`	`"studio" \| "sunset" \| "night"`	`"studio"`	Procedural lighting preset; it makes no network request.
`label`	`string`	`"Interactive 3D model"`	Accessible description.
`onError`	`(error: unknown) => void`	`-`	Called when `src` fails to load.
`fallback`	`ReactNode`	gradient	Static frame shown while loading and when WebGL is unavailable.
`className`	`string`	`-`	Classes for the outer element.

Models are fitted to the view automatically. Draco-compressed models fetch their decoder from a CDN on first use.

three.js loads only when the component comes within 200px of the viewport, in its own chunk, so pages that do not show it never download it.
Rendering pauses while it is offscreen or the tab is hidden, and the pixel ratio is capped at 2.
With prefers-reduced-motion: reduce it renders a single still frame.
Without WebGL, or before the scene loads, a static gradient is shown instead.
Colours come from your theme's CSS variables and update when the theme changes.