import {
AmbientLight, DAY, Daylight, defineEnvironment, DirectionalLight, Environment, HemisphereLight, PointLight, SpotLight,
} from "@apricot/react";
import type { DaylightKey, StudioOptions } from "@apricot/react";Light components add to the scene's look. With look="none" they are the only lights. intensity, position and target accept plain or shared values, so lights can move and dim every frame at no cost. Every light takes a ref (its three.js light) and renders nothing itself.
Lights#
Common props:
| Prop | Type | Default |
|---|---|---|
color |
colour | "#ffffff" |
intensity |
number or shared value |
1 |
| Component | Own props (default) | Light |
|---|---|---|
AmbientLight |
From everywhere, no shading: lifts shadows evenly | |
HemisphereLight |
sky ("#ffffff", replaces color), ground ("#8a7a6a") |
One colour from above, another bounced from below. Soft outdoor light |
DirectionalLight |
position ([3, 5, 4]), target ([0, 0, 0]), castShadow |
Sunlight: parallel rays from position towards target |
PointLight |
position ([0, 2, 0]), distance (0: no limit, fades with distance) |
A bulb: every direction from a point |
SpotLight |
position ([0, 4, 2]), target ([0, 0, 0]), angle half-angle in radians (0.5), penumbra edge softness 0–1 (0.3), distance (0) |
A cone from position towards target |
In a scene with shadows, the brightest directional light casts them. castShadow on a DirectionalLight makes it the one that casts (true) or never casts (false).
Environment#
Sets what metals and glossy materials reflect, while mounted. Everything is live: switching fades between environments, and rotation, intensity and the boxes change every frame without rebuilding shaders.
| Prop | Type | Default | Description |
|---|---|---|---|
name |
string |
"studio", "soft", "sunset", "night", or a name from defineEnvironment |
|
sky |
[ceiling, horizon, floor] colours |
Or describe one… | |
boxes |
SoftBox[] |
…with soft boxes. Moving them is free | |
intensity |
number or shared value |
1 |
Brightness multiplier |
rotation |
number or shared value (radians) |
0 |
Turns the studio around the vertical axis |
transition |
seconds | 0.6 |
How long a change of name, sky or boxes fades. 0 is instant |
<Scene environment="…"> sets the starting environment; <Environment> changes it later.
<Environment name={night ? "night" : "studio"} rotation={swipeAngle} />defineEnvironment(name, options: StudioOptions)#
Registers a studio by name.
StudioOptions field |
Type | Description |
|---|---|---|
sky |
[ceiling, horizon, floor] colours |
The gradient around the object |
boxes |
SoftBox[] |
Soft boxes: the highlights. Six fit in the built-in slots; more cost a shader rebuild |
intensity |
number | Overall brightness (default 1) |
SoftBox field |
Type | Description |
|---|---|---|
direction |
[x, y, z] |
From the object towards the box, world space. +z is towards the default camera |
size |
[halfWidth, halfHeight] |
In radians |
intensity |
number | Brightness; above 1 for highlights |
color |
colour | Default white |
Built-in environments:
| Name | Look |
|---|---|
studio |
Dark grey studio: key box above and in front, tall strips on both sides, a soft top light, a faint rim behind, a dim fill from the camera side |
soft |
Light and even: pale products, white phones, soft paint |
sunset |
A low warm sun behind and to the side, an orange horizon, a cool sky |
night |
Dark, with coloured neon strips on the sides and a thin light above |
Daylight#
Sun, sky light and background for a time of day. Use it with look="none". Everything is a live value, so a day cycle driven by a slider costs nothing per frame. With an environment, reflections dim at night.
| Prop | Type | Default | Description |
|---|---|---|---|
time |
number or shared value |
required | Hour, 0–24 (13.5 is half past one). Plain values animate; shared values are followed exactly |
transition |
seconds | 1.5 |
How long a plain change of time takes |
background |
boolean | true |
Sets the background and fog to the sky colour |
north |
radians | 0 |
Turns the compass: where the sun rises (0: east is +x) |
keys |
DaylightKey[] |
DAY |
The day's colours. Replace them for another mood |
sunrise, sunset |
hours | 6, 19 |
When the sun comes up and goes down |
<Scene look="none" environment="soft" fog shadows>
<Daylight time={night ? 21 : 13} />
</Scene>DAY has keys at 0, 5.5, 6.5, 9, 13, 17, 18.8 and 20 hours. A DaylightKey: { hour, sun, sunIntensity, sky, ground, fillIntensity, background, reflections }, interpolated between keys.
Shadows per object#
With <Scene shadows>, meshes cast and receive, flat ones (floors) only receive, and see-through ones do neither. Override per object with castShadow and receiveShadow props on shapes, Mesh, Model and Instances. For three.js objects of your own, setShadow(object, { cast, receive }) from @apricot/core does the same.