Stage 3D

ProNew

A lazily loaded WebGL canvas for react-three-fiber scenes that pauses offscreen, respects reduced motion, caps the pixel ratio and falls back to a static frame without WebGL.

Customize

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

Guide and examples

Installation


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

Usage

Props

Prop	Type	Default	Description
`children`	`ReactNode \| (stage: StageState) => ReactNode`	`-`	Scene content. The function form receives `animate` and a `pointer` ref.
`label`	`string`	`-`	Accessible description. When set the stage is `role="img"`; otherwise it is decorative and `aria-hidden`.
`fallback`	`ReactNode`	gradient	Shown while loading and without WebGL.
`camera`	`CanvasProps["camera"]`	`{ position: [0, 0, 6], fov: 45 }`	Camera options.
`dpr`	`[number, number]`	`[1, 2]`	Device pixel ratio range.
`loadMargin`	`string`	`"200px"`	How far ahead of the viewport to start loading.
`windowPointer`	`boolean`	`false`	Track the pointer on the whole window, for backgrounds under other content.
`canvasProps`	`CanvasProps`	`-`	Extra props for the react-three-fiber `<Canvas>`.
`className`	`string`	`-`	Classes for the outer element.

Helpers

The file also exports the hooks the 3D components use: useThemeColors (resolves CSS variables such as --primary, including oklch() values, to hex and re-reads them when the theme changes), usePrefersReducedMotion, usePageVisible, useInView, useStableArray, detectWebGL and neverOnServer.

Put three.js code in its own file and load it with React.lazy behind a typeof window guard, as above. The page bundle then stays free of three.js, and so does the server bundle, which matters on edge runtimes with size limits.

Performance and accessibility

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

Installation


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

Usage

Props

Prop	Type	Default	Description
`children`	`ReactNode \| (stage: StageState) => ReactNode`	`-`	Scene content. The function form receives `animate` and a `pointer` ref.
`label`	`string`	`-`	Accessible description. When set the stage is `role="img"`; otherwise it is decorative and `aria-hidden`.
`fallback`	`ReactNode`	gradient	Shown while loading and without WebGL.
`camera`	`CanvasProps["camera"]`	`{ position: [0, 0, 6], fov: 45 }`	Camera options.
`dpr`	`[number, number]`	`[1, 2]`	Device pixel ratio range.
`loadMargin`	`string`	`"200px"`	How far ahead of the viewport to start loading.
`windowPointer`	`boolean`	`false`	Track the pointer on the whole window, for backgrounds under other content.
`canvasProps`	`CanvasProps`	`-`	Extra props for the react-three-fiber `<Canvas>`.
`className`	`string`	`-`	Classes for the outer element.

Helpers

Performance and accessibility

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.