Navigate

Search topics across all sections

GitHub
Staging

Sky & Stars

Sky gives you a realistic procedural atmosphere — blue skies at noon, warm oranges at sunset, deep reds at dawn. Stars fills the background with a twinkling starfield for space and night scenes. Both are lightweight, require no image downloads, and render in a single shader pass.

You add a Sky component with the sun low on the horizon. It looks beautiful — warm sunset colors across the dome. But your objects have no shadows, and the light direction does not match the sun at all. You spin the sky to move the sun, but the shadows stay fixed. Turns out, Sky is purely visual. It does not emit any light.

terminal
Objects are unlit despite a visible sun in the sky. Sky component does not provide scene lighting or cast shadows.

Real-world

Think of a planetarium. You walk into the dome and look up. The projector paints a realistic sky overhead — the sun in the right position, scattered blue light, warm colors near the horizon. It looks exactly like being outside.

But it is just a projection. The dome does not actually warm you, and there is no real sunlight casting shadows on the seats. If the planetarium wanted shadows, they would need to add a separate spotlight pointing from where the projected sun sits.

The Sky component is that planetarium dome. It projects a physically-based atmosphere using atmospheric scattering math. Beautiful to look at, but you still need a directional light for actual illumination and shadows.

How Sky and Stars Work

Sky handles daytime atmospheres. Stars handles nighttime particle fields. They serve different purposes but can be layered for dusk scenes.

Sky

Atmospheric shader on a sphere

sunPosition

Controls time of day and colors

Directional Light

Must match sun for shadows

Stars (optional)

Point particles for night sky

Guided Walkthrough

Let us build three scenes: a bright day, a starry night, and a layered dusk.

Step 1 — A daytime sky with matching light

DaytimeSky.tsxTSX
import { Sky } from '@react-three/drei'

const sunPos = [1, 0.5, 0]

<>
  <Sky
    sunPosition={sunPos}
    turbidity={8}
    rayleigh={6}
    mieCoefficient={0.005}
    mieDirectionalG={0.8}
  />
  {/* Light must match the sun direction */}
  <directionalLight
    position={sunPos}
    intensity={1.5}
    castShadow
  />
</>

sunPosition controls where the sun sits. Turbidity is haze density, rayleigh controls blue scattering. The key rule: always pair Sky with a directional light at the same position. Sky is just the painting on the dome, the light does the real work.

Step 2 — A starry night scene

StarryNight.tsxTSX
import { Stars } from '@react-three/drei'

<>
  <color attach="background" args={['#000010']} />
  <Stars
    radius={100}
    depth={50}
    count={5000}
    factor={4}
    saturation={0}
    fade
    speed={1}
  />
</>

For night, skip Sky entirely and use a dark background color. Stars creates point particles scattered in a sphere. The fade prop softens the edges, speed rotates the whole field slowly, and factor controls how big the stars appear.

Step 3 — A dusk scene with Sky and Stars layered

DuskScene.tsxTSX
<>
  <Sky
    sunPosition={[1, 0.05, 0]}
    turbidity={10}
    rayleigh={3}
  />
  <Stars
    radius={200}
    count={3000}
    factor={3}
    fade
    speed={0.5}
  />
  <directionalLight
    position={[1, 0.05, 0]}
    intensity={0.8}
    color="#ff7b00"
  />
</>

Position the sun barely above the horizon for warm dusk colors. High turbidity adds more haze. Stars become visible in the darker upper sky. Tint the directional light orange to match the sunset mood.

What you just learned

Sky renders a procedural atmosphere based on physically-based scattering math

Sky is purely visual — it does not emit light. Always pair it with a directional light

sunPosition controls the time of day: high = noon, low = sunset, below = not great for night

Stars creates a particle-based starfield. Use fade and reduce count on mobile

For night scenes, skip Sky and use a dark background color with Stars

Question

Sky provides a beautiful background but no lighting. Environment provides lighting and reflections but loads an image file. Can you use both together — Sky for the visible backdrop and Environment (without background) for the reflections? What would that look like?

Think about it...

You have a scene with <Sky sunPosition={[0, 2, 0]} /> and nothing else. What does the scene look like?

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

Slide sun to sunset — golden hour!

Try This!

Beginner

Set rayleigh to 10 — alien sky!

Try This!

Beginner

Set starCount to 10000 — starry night

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

1
Not syncing directional light with sun position
Shadows point the wrong direction from the visible sun
Don't do this
Experience.tsxTSX
<>
  {/* Sun appears on the right */}
  <Sky sunPosition={[10, 2, 0]} />
  {/* But light comes from the LEFT! */}
  <directionalLight position={[-5, 5, 0]} castShadow />
</>
Sky is purely visual — it renders a sky shader but emits no light. You need a separate directional light to illuminate your scene. If the light direction does not match the sun position, shadows point the wrong way and the illusion breaks. Always share the same position vector for both.
2
Too many stars on mobile devices
Frame rate drops on phones and low-end GPUs
Don't do this
AdaptiveStars.tsxTSX
<Stars
  count={10000}
  factor={6}
  speed={2}
/>
// 10,000 animated particles on a phone = lag
Stars renders each star as a point particle. High counts with large factor sizes and animation can stress mobile GPUs. Reduce count to 1,000-2,000 on phones, lower the factor, and set speed to 0 to disable rotation. The fade prop hides reduced density by fading stars at the edges.
3
Using Sky for a night scene
Sky still glows even when the sun is below the horizon
Don't do this
NightScene.tsxTSX
// Sun below horizon but sky still shows color
<Sky sunPosition={[0, -1, 0]} />
<Stars count={5000} />
Sky's atmospheric scattering model does not produce true darkness even with the sun below the horizon. It still shows a dim gradient that washes out stars. For night scenes, use a dark background color and Stars alone. For dusk or twilight, position the sun just above the horizon with high turbidity.

Best Practices

Sync light with sun

Always add a directional light matching the Sky's sunPosition. Share the same variable for both to keep them in sync automatically.

Dark BG for night

For night scenes, use <color attach="background" /> instead of Sky. The atmospheric shader cannot produce true darkness.

Reduce stars on mobile

Keep star count under 2,000 on mobile. Set speed={0} to disable rotation animation and use the fade prop.

Prefer Sky over HDRI for sky

When you just need a sky background with no reflections, Sky is cheaper. Zero download, zero loading time, and fully adjustable via props.