Navigate

Search topics across all sections

GitHub
Staging

Stage Component

Stage is the "make it look good" button. Wrap any 3D object in a Stage component and it instantly gets professional lighting, soft contact shadows, environment reflections, and auto-centering. Zero configuration, polished results.

You load a 3D model and it looks fine, so you add an ambient light, a directional light, and an Environment component for reflections. Then you add ContactShadows for a ground shadow and Center to position it properly. That is five separate components to configure. You tweak each one for an hour. Then your colleague drops the model inside <Stage> and it looks just as good in 10 seconds.

terminal
Spending hours manually configuring lighting, shadows, and centering when Stage does it all in one line.

Real-world

Imagine walking into a professional photo studio. The backdrop is already set up. The lights are positioned in a classic portrait arrangement. The floor has a subtle reflection. The camera is framed so the subject fills the shot perfectly.

You do not need to understand photography lighting to take a great photo in that studio. You just put your subject on the mark, and everything looks polished.

Stage is that photo studio. It sets up the backdrop (Environment), positions the lights (preset lighting), adds a floor shadow (ContactShadows), and centers the subject (Center). You just drop your model inside.

What Stage Bundles Together

Stage is a convenience wrapper around four things you would otherwise set up manually.

Environment

IBL lighting + reflections

Light Preset

rembrandt, portrait, upfront, or soft

ContactShadows

Soft ground shadow beneath the object

Center

Auto-positions model at the origin

Guided Walkthrough

From zero to a polished product shot in three steps.

Step 1 — Wrap your model in Stage

BasicStage.tsxTSX
import { Stage, OrbitControls } from '@react-three/drei'

<>
  <OrbitControls makeDefault />
  <Stage>
    <mesh>
      <torusKnotGeometry args={[1, 0.3, 128, 32]} />
      <meshStandardMaterial
        color="royalblue"
        metalness={0.8}
        roughness={0.2}
      />
    </mesh>
  </Stage>
</>

That is it. The torus knot is now centered, lit with environment lighting, and has a soft contact shadow on the ground. No extra lights needed.

Step 2 — Pick a lighting preset

LightingPresets.tsxTSX
{/* rembrandt: dramatic, directional */}
{/* portrait:  soft, even */}
{/* upfront:   bright, flat */}
{/* soft:      diffused, organic */}

<Stage
  preset="rembrandt"
  intensity={0.5}
  environment="city"
>
  <YourModel />
</Stage>

Each preset mimics a classic photography lighting setup. Rembrandt is dramatic with strong directional shadows. Portrait is soft and even. Try all four to see which suits your model best. Adjust intensity to make it brighter or dimmer.

Step 3 — Know when to break out of Stage

StageVsManual.tsxTSX
{/* Stage: quick, all-in-one */}
<Stage preset="soft">
  <ProductModel />
</Stage>

{/* Individual components: full control */}
<Environment preset="warehouse" background blur={0.5} />
<ContactShadows position={[0, -0.5, 0]} opacity={0.4} />
<Center top>
  <ProductModel />
</Center>

Stage is perfect for 80% of cases. But if you need a visible background, custom shadow settings, or fine-grained light placement, use the individual components it is built from. You are not locked in.

What you just learned

Stage bundles Environment, lighting, ContactShadows, and Center into one component

You do not need to add any extra lights — Stage provides everything

Four presets (rembrandt, portrait, upfront, soft) mimic classic photography setups

Use the intensity prop to adjust brightness instead of adding separate lights

When you need more control, break out into the individual components Stage wraps

Question

Stage auto-centers your model and adjusts the camera to frame it. What happens if you put two objects far apart inside Stage? Does each one get its own spotlight, or does Stage treat them as a single group? (Hint: think about bounding boxes.)

Think about it...

You have a 3D model that is positioned at [5, 3, -2] in world space. You wrap it in a <Stage> component. Where does the model appear on screen?

Try These Challenges

Put what you learned into practice. Try each challenge in the demo above using the Leva controls, then check the solution.

Try This!

Beginner

Try all 4 presets — which is your favorite?

Try This!

Beginner

Toggle shadows off — flatter look

Try This!

Beginner

Set intensity to 0 — only ambient light

These are the patterns that trip up developers most often. Switch between Wrong and Fixed to compare the code side by side.

1
Adding extra lights alongside Stage
Over-lit scene with blown-out highlights
Don't do this
Experience.tsxTSX
<>
  <Stage preset="rembrandt">
    <MyModel />
  </Stage>
  {/* Stage already provides lighting! */}
  <ambientLight intensity={1} />
  <directionalLight intensity={2} />
</>
Stage is an all-in-one solution that includes environment-based lighting, contact shadows, and centering. Adding extra lights on top causes over-exposure with blown-out highlights and lost detail. If Stage's lighting is too dim or too bright, adjust its intensity prop or environment preset. If you need full control, skip Stage and use Environment + individual lights.
2
Nesting Stage inside another Stage
Double lighting causes visual artifacts
Don't do this
Experience.tsxTSX
<Stage preset="rembrandt">
  <Stage preset="portrait">
    <MyModel />
  </Stage>
</Stage>
Each Stage creates its own complete lighting setup with environment maps, shadows, and centering. Nesting one inside another doubles the lighting and creates conflicting shadow planes. Always use a single Stage wrapper. If different objects need different presentations, use separate Canvases.
3
Using Stage for large multi-area scenes
Auto-centering and camera framing break for spread-out objects
Don't do this
ComplexScene.tsxTSX
<Stage adjustCamera>
  {/* Stage treats ALL children as one group */}
  <Room position={[-10, 0, 0]} />
  <Garden position={[10, 0, 0]} />
  <Sky position={[0, 20, 0]} />
</Stage>
Stage is designed for presenting a single model or small group, like a product viewer. It auto-centers all children as one bounding box and frames the camera around them. For complex scenes with multiple distant areas, this auto-framing breaks down. Use Environment, ContactShadows, and Center separately for full control.

Best Practices

No extra lights

Stage provides all the lighting. Use the intensityprop to adjust brightness instead of adding ambient or directional lights alongside it.

Try all four presets

Each preset creates a different mood. Spend two minutes switching between rembrandt, portrait, upfront, and soft to find the best match for your model.

Use for presentations

Stage is ideal for product pages, model viewers, portfolio pieces, and demos. It handles the common case with zero configuration.

Break out when needed

If Stage is too opinionated, use Environment + ContactShadows + Center separately. You get the same pieces with full control over each one.