Skip to Content

Scene

Scene parts for building a full-bleed background from layers: a frame that sets the horizon, a ground, lights, a flat or curved horizon, discs and rings, corner lights, a reflection, a fade and grain. Moving the horizon moves every layer with it.

Installation

pnpm dlx shadcn@latest add @01orbital/scene

Usage

import {
  Scene,
  SceneBody,
  SceneDisc,
  SceneFade,
  SceneGrain,
  SceneGround,
  SceneLight,
  SceneLimb,
  SceneRig,
} from "@/components/scene/scene"

// Soft noise: an SVG turbulence filter as a data URI.
const SOFT_NOISE = `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'%3E%3Cfilter id='n' color-interpolation-filters='sRGB'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.7' numOctaves='5' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E")`
// One light for the whole scene: its color, and the direction it comes from
// in degrees (0 is straight above, 90 from the right). Change these two and
// every lit layer follows.
const LIGHT = "oklch(0.9 0.055 45)"
const ANGLE = 45

const SIN = Math.sin((ANGLE * Math.PI) / 180)
const COS = Math.cos((ANGLE * Math.PI) / 180)

// The light at a given strength, 0 to 1.
const lit = (strength: number) =>
  `color-mix(in oklab, ${LIGHT} ${strength * 100}%, transparent)`

// The sun sits off to the side the light comes from.
const SUN_X = `${50 + 17 * SIN}%`

// The night sky, from the top edge (0) to the horizon (1).
const SKY = [
  ["oklch(0.125 0.008 268)", 0],
  ["oklch(0.155 0.012 270)", 0.8],
  ["oklch(0.16 0.012 268)", 1],
] as const

// The planet's surface, from its lit edge down.
const SURFACE = [
  [LIGHT, "0px"],
  [lit(0.9), "3px"],
  [`color-mix(in oklab, ${LIGHT} 40%, oklch(0.2 0.018 275 / 0.6))`, "26px"],
  ["oklch(0.20 0.018 275 / 0.9)", "110px"],
  ["oklch(0.115 0.009 265)", "260px"],
  ["oklch(0.10 0.008 265)", "100%"],
] as const

// The scene has no height of its own; the frame gives it the whole stage.
export default function SceneDemo() {
  return (
    <Scene horizon={44} className="dark">
      <SceneGround sky={SKY} space={null} />
      <SceneRig
        keyLight={lit(0.13)}
        counterLight="oklch(0.5 0.05 252 / 0.1)"
        keyAt={`${50 + 87.7 * SIN}% ${50 - 87.7 * COS}%`}
        counterAt={`${50 - 83.4 * SIN}% ${50 + 83.4 * COS}%`}
      />
      <SceneLight
        className="rounded-full mix-blend-screen blur-sm"
        shape="circle"
        space={null}
        x={SUN_X}
        y="22%"
        width="300px"
        height="300px"
        color={lit(0.32)}
        mid={[lit(0.13), 34]}
        falloff={66}
      />
      <SceneBody x={SUN_X} y="22%">
        <SceneDisc
          size={104}
          color="oklch(0.135 0.012 262)"
          glow={`inset 0 0 0 1.5px ${lit(0.95)}, inset 0 0 14px 3px ${lit(0.4)}`}
        />
      </SceneBody>
      <SceneLimb
        x={SUN_X}
        surface={SURFACE}
        glow={`0 -30px 46px 6px ${lit(0.14)}, 0 -14px 70px 10px ${lit(0.3)}, 0 -4px 22px 2px ${lit(0.3)}`}
      />
      <SceneFade
        color="oklch(0 0 0 / 0.3)"
        at={`${50 + 12 * SIN}% ${50 - 12 * COS}%`}
        clear={45}
      />
      <SceneGrain recipe={SOFT_NOISE} opacity={0.055} size="512px" />
    </Scene>
  )
}

This example installs with everything it uses:

pnpm dlx shadcn@latest add @01orbital/scene-demo

Anatomy

Scene is built from 14 parts. In the example they nest like this:

Scene
├─ SceneGround
├─ SceneRig
├─ SceneLight
├─ SceneBody
│  └─ SceneDisc
├─ SceneLimb
├─ SceneFade
└─ SceneGrain
  • Scene: The frame: a full-bleed art layer for a relative parent. It clips its layers, keeps their blending to itself, ignores the pointer and is hidden from screen readers.
  • SceneGround: The ground: what the scene is painted on. Pass color for a flat ground, or sky and land for two bands that meet at the horizon. Each band's stops run from 0 to 1 along the band, so moving the horizon stretches one band and squeezes the other without touching the colors.
  • SceneRig: Corner lights: a key light entering from one corner outside the frame and a quieter counter light from the opposite corner. Both are screen-blended and blurred, so they tint the scene without showing a source. Optional; a scene works without it.
  • SceneLight: One light: a soft ellipse that fades to nothing. It is centered on x and y; y defaults to the horizon. falloff is how far out the light reaches, as a share of the ellipse.
  • SceneBody: A point in the scene that shapes hang from: put SceneRing and SceneDisc inside and they center on it. y defaults to the horizon.
  • SceneDisc: A filled disc centered on its SceneBody, with an optional glow.
  • SceneLimb: A curved horizon: the lit edge of something very large, such as a planet. It is an ellipse far wider than the scene, so only its top arc shows. A wider ellipse is a flatter curve. Its top sits on --scene-horizon.
  • SceneFade: A fade: the scene darkening (or lightening) toward its edges. The middle stays clear out to clear, then color comes in.
  • SceneGrain: The grain: a texture laid over everything below it, blended as an overlay. recipe is a CSS image, such as one from the kit's grain recipes.
  • SceneGlaze: A glaze: a wide wash of color laid over one side of the horizon. It hangs from the top or bottom edge and reaches reach past the horizon, so two glazes overlap where they meet. Moving the horizon resizes both.
  • SceneHorizon: The horizon as a line of light: bright at x, fading toward both ends, with a near and a far glow around it. It sits on --scene-horizon.
  • SceneRing: A thin ring centered on its SceneBody, with an optional glow.
  • SceneClip: A clip at the horizon: its children show only above the horizon, or only below it. They keep the scene's own coordinates, so a SceneBody inside sits where it would outside. Blended layers inside it blend with each other only.
  • SceneReflection: A reflection: its children, mirrored in the horizon and shown below it, fading with depth. Pass the same layers you drew above the horizon. stretch lengthens the mirror image, the way water does.

API reference

Scene

The frame: a full-bleed art layer for a relative parent. It clips its layers, keeps their blending to itself, ignores the pointer and is hidden from screen readers.

horizon is how far down the horizon sits, as a share of the height. Every part inside reads it as --scene-horizon, so the scene has one horizon.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneGround

The ground: what the scene is painted on. Pass color for a flat ground, or sky and land for two bands that meet at the horizon. Each band's stops run from 0 to 1 along the band, so moving the horizon stretches one band and squeezes the other without touching the colors.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneRig

Corner lights: a key light entering from one corner outside the frame and a quieter counter light from the opposite corner. Both are screen-blended and blurred, so they tint the scene without showing a source. Optional; a scene works without it.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneLight

One light: a soft ellipse that fades to nothing. It is centered on x and y; y defaults to the horizon. falloff is how far out the light reaches, as a share of the ellipse.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneBody

A point in the scene that shapes hang from: put SceneRing and SceneDisc inside and they center on it. y defaults to the horizon.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneDisc

A filled disc centered on its SceneBody, with an optional glow.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneLimb

A curved horizon: the lit edge of something very large, such as a planet. It is an ellipse far wider than the scene, so only its top arc shows. A wider ellipse is a flatter curve. Its top sits on --scene-horizon.

surface lists the colors from the lit edge down. A depth given as a number is a share of the scene's height, so it scales with the scene; a depth given as a string is a fixed CSS length, which suits the thin lit rim. With bands="level" the colors lie in flat layers, which only looks right on a gentle curve. With bands="curve" they follow the edge, so the rim stays lit all the way along a tight curve.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneFade

A fade: the scene darkening (or lightening) toward its edges. The middle stays clear out to clear, then color comes in.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneGrain

The grain: a texture laid over everything below it, blended as an overlay. recipe is a CSS image, such as one from the kit's grain recipes.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneGlaze

A glaze: a wide wash of color laid over one side of the horizon. It hangs from the top or bottom edge and reaches reach past the horizon, so two glazes overlap where they meet. Moving the horizon resizes both.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneHorizon

The horizon as a line of light: bright at x, fading toward both ends, with a near and a far glow around it. It sits on --scene-horizon.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneRing

A thin ring centered on its SceneBody, with an optional glow.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneClip

A clip at the horizon: its children show only above the horizon, or only below it. They keep the scene's own coordinates, so a SceneBody inside sits where it would outside. Blended layers inside it blend with each other only.

Prop

Type

It also accepts the HTML attributes of the element it renders.

SceneReflection

A reflection: its children, mirrored in the horizon and shown below it, fading with depth. Pass the same layers you drew above the horizon. stretch lengthens the mirror image, the way water does.

Prop

Type

It also accepts the HTML attributes of the element it renders.

Dependencies

npm: cn. The CLI installs it for you.

Last updated on