# Street light
> A line-drawn street with an LED street light: change its height, tilt and optic and watch where the light lands.
A technical figure of a terraced street at night. Pick a narrow, wide or asymmetric optic, drag the pole’s height and the head’s tilt, and the light on the road, the gardens, the houses and the sky is computed as you go, with the BUG rating, road lux and the lux on a bedroom window. A lux map turns the light into false colour with isolux lines.
A React component by Bruno Delorence: https://brunodelorence.com/components/street-light. MIT License, Copyright (c) 2026 Bruno Delorence.
Category: Motion.
## Anatomy
1. **Figure**: The street drawn on a canvas at the device’s pixel ratio, lit by the lantern’s photometry. Dragging on it sets the height (up and down) and the tilt (left and right); it is one image to a screen reader, labelled with the settings.
2. **Pole height**: A native range from 5 to 12 m in steps of 0.1, its value in an `output` above it: a 2 px rule and a hollow 14 px ring.
3. **Tilt**: The same slider, 0 to 25°: it turns the head towards the houses, so the light reaches further across the street.
4. **Optics**: A radio group of three cards, keys 1 to 3; each names its optic and the BUG rating it earns on an 8 m pole. The picked one takes the strong edge.
5. **Distribution**: One stacked bar of where the flux goes (road, pavements, behind the pole, gardens, houses, sky), its legend under it with each share.
6. **Stats**: The BUG rating, the road’s average and peak lux and the lux on the bedroom window, read from the same model as the picture.
7. **Lux map**: A toggle button (`aria-pressed`, key L) that cross-fades the warm light into false colour with isolux lines.
8. **Readout**: The summary line under the panel; the same words are read out politely once the settings rest.
## When to use
- Explaining a physical trade-off by letting the reader move it: how pole height, tilt and optic change where the light lands.
- A long-form article or report on lighting, light pollution or street design, where one interactive figure carries the argument.
- Teaching the vocabulary of a field (BUG rating, lux, isolux lines) next to the picture it describes, so every number has a place.
- A figure that should read as a drawing first: hairlines, captions and small tracked capitals, in a dark or a light scheme.
## When not to use
- Real lighting design or compliance work. The model is a teaching one; use photometric software fed with the luminaire’s IES file.
- Reporting measured data. Use a chart or a table of the readings, not a simulation that looks like one.
- A dense dashboard tile. The figure needs about 600 px to read; a small stat card or a sparkline fits better.
- Pages without room for a canvas to repaint (long lists, many instances): one figure per page, or a static image for the rest.
## Installation
Install it with the shadcn CLI, into components/street-light of any React project:
```sh
npx shadcn@latest add https://brunodelorence.com/r/street-light.json
```
Or add the registry to components.json once, as a namespace that coding agents and the shadcn MCP server search by name:
```json
{
"registries": {
"@brunodelorence": "https://brunodelorence.com/r/{name}.json"
}
}
```
```sh
npx shadcn@latest add @brunodelorence/street-light
```
Or copy all the source files below into one folder of your project. Either way it needs React 19 and a bundler with CSS Modules (Next.js, Vite).
It has a dark colour scheme. Its colours are CSS light-dark() pairs, kept inside @supports so that builds which rewrite light-dark() for older browsers leave them alone: it follows your page’s color-scheme (light unless the page sets one) or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
## Usage
```tsx
import { StreetLight } from './street-light';
export function LightingFigure() {
return ;
}
```
## States
- **Asymmetric**: The default: the light is thrown forward across the road, with little behind the pole.
- **Narrow**: A tight spot on the road by the pole: bright in its beam, dark at the far kerb.
- **Wide**: An even spread that spills onto the pavements, the gardens and the houses.
- **Tilted 20°**: The head turned towards the houses: the road gets more, and so do the windows and the sky.
- **Short pole, 5 m**: Brighter under the lantern, a smaller pool around it.
- **Tall pole, 12 m**: A wider, dimmer pool: the same flux spread over more street.
- **Lux map on**: False colour on a log scale from 0.5 to 100 lx, with isolux lines; set with `defaultLuxMap`.
- **Dark scheme**: With `colorScheme="dark"`: hairlines over near-black faces, the light a warm glow.
- **Light scheme**: With `colorScheme="light"` the panel’s tokens and the canvas palette turn to paper and ink.
- **Narrow container**: Under 600 px wide the sliders and the optic cards stack, and the stats sit two by two.
## How it works
- The street is a small 3D model in metres, drawn in a parallel projection: every solid shows its top, its front and its right end, painted far to near on a canvas at the device’s pixel ratio, with 1 px hairlines over near-black faces.
- The light is a point source with a candela distribution per optic, all three at the same flux. The wide and asymmetric lenses turn with the head’s tilt; the narrow one is aimed back at the kerb and follows the tilt by a third, so its spot stays on the road by the pole. Every lit face gets a texture of illuminance, E = I · cos θ / d², 0.25 m a texel; the ground shares one texture, laid on each horizontal face through the plane’s affine map.
- Where the light goes is found by tracing a fixed grid of directions from the lens: each lands on the road, a pavement, the ground behind the pole, a garden, the houses or the sky, and the shares fill the stacked bar. The BUG rating reads the same directions: light behind the head, above the horizon, and at high angles.
- With the lux map on, the road, the near pavement and the facade take a colour on a logarithmic scale from 0.5 to 100 lx, with isolux lines (1, 2, 5, 10, 20, 50, 100, 200 lx) traced by marching squares over the same grids; the other faces keep a softer warm light, and the haze around the head stays. The two views cross-fade.
- A change of optic cross-fades the candela tables over a second, so the light, the bar and every number slide to their new values together; the picked LED module lifts out of its tray at the front of the plinth.
- Dragging on the figure sets the height (up and down) and the tilt (left and right). While on screen and untouched, a demo pointer switches optics, tilts the head, turns the lux map on and drags the height; any real input hands control to the reader.
- Painting runs only while something moves. Its colours follow the page’s color-scheme, or the colorScheme prop: the panel uses light-dark() tokens, and the canvas repaints when a probe in the stylesheet changes colour.
## API reference
- **defaultOptic** (`'narrow' | 'wide' | 'asymmetric'`, default `'asymmetric'`): The optic in the head when it mounts.
- **defaultHeight** (`number`, default `8`): The pole’s height in metres, from 5 to 12.
- **defaultTilt** (`number`, default `0`): The head’s tilt towards the houses, in degrees, from 0 to 25.
- **defaultLuxMap** (`boolean`, default `false`): Starts with the lux map on.
- **onChange** (`(settings: { optic, height, tilt, luxMap }) => void`): Called with the settings whenever the reader or the demo changes them.
- **autoplay** (`boolean`, default `true`): While on screen and untouched, a demo pointer plays with the controls. It never runs under reduced motion.
- **colorScheme** (`'light' | 'dark' | 'system'`): Light or dark colours, or the reader’s. Without it, the component follows the page’s color-scheme.
- **className** (`string`): A class for the root, to size or place it.
## Accessibility
- Height and tilt are native range inputs with their values spoken in metres and degrees; the optics are a radio group, and the lux map is a toggle button with aria-pressed.
- Keys 1, 2 and 3 pick an optic and L turns the lux map on or off, anywhere in the component.
- The figure is an image with a label that states the pole’s height, the tilt and the optic; the drag on it only repeats what the sliders do.
- The summary line (rating, road share, sky share, window lux) is read out politely once the settings rest, not at every step of a drag.
- Under reduced motion the lamp is on from the start, changes are instant and the demo never runs. The demo pointer is hidden from screen readers.
## Source
### street-light/street-light.tsx
```tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.
'use client';
import {
useEffect,
useEffectEvent,
useId,
useRef,
useState,
type PointerEvent as ReactPointerEvent,
} from 'react';
import { DemoPointer, runDemo, type Point } from './demo-pointer';
import {
OPTICS,
WINDOW,
ZONES,
lanternAt,
ratingText,
report,
type Lantern,
type Mix,
type Optic,
type Rating,
type Zone,
} from './photometry';
import { PALETTES, Renderer } from './renderer';
import { build, headPoints } from './scene';
import { useAutoplay } from './use-autoplay';
import styles from './street-light.module.css';
/*
* Street light: a figure of an LED street light over a terraced street, drawn as an axonometric
* line diorama, with the light it throws computed as you change it.
*
* - The pole's height, the head's tilt and the optic (narrow, wide or asymmetric) set a lantern;
* photometry.ts turns it into lux on every surface (inverse square and cosine, from a candela
* distribution per optic, all at the same flux) and into the share of the flux that lands on
* the road, the pavements, behind the pole, in the gardens, on the houses and in the sky, with
* a BUG rating (backlight, uplight, glare).
* - renderer.ts paints the scene on a canvas: hairlines on near-black faces, the light as a warm
* texture on each face, or, with the lux map on, as a false-colour map with isolux lines.
* - Dragging on the figure sets the height (up and down) and the tilt (left and right); the
* sliders, the optic cards (keys 1, 2, 3) and the lux map switch (L) do the same by keyboard.
* - Changes of optic cross-fade the candela tables over a second, so the light, the numbers and
* the bar all slide to their new values together; the lux map fades in and out.
* - While on screen and untouched, a demo pointer switches optics, tilts the head, turns the lux
* map on and drags the height. Any real input hands control to the reader.
* - Light or dark: the panel's colours are light-dark() tokens; the canvas reads the scheme from a
* probe in the stylesheet and repaints when it changes.
*/
const LABELS: Record = { narrow: 'Narrow', wide: 'Wide', asymmetric: 'Asymmetric' };
const ZONE_LABELS: Record = {
road: 'Road',
pavements: 'Pavements',
behind: 'Behind pole',
gardens: 'Gardens',
houses: 'Houses',
sky: 'Sky',
};
export const HEIGHT = { min: 5, max: 12, step: 0.1 };
export const TILT = { min: 0, max: 25, step: 0.1 };
const rad = (deg: number) => (deg * Math.PI) / 180;
const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
const ease = (t: number) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
const mixOf = (optic: Optic): Mix => ({ narrow: 0, wide: 0, asymmetric: 0, [optic]: 1 });
/** The rating each optic earns on an 8 m pole, untilted: the line under its name. */
const CARD_RATINGS: Record = (() => {
const out = {} as Record;
for (const optic of OPTICS) {
out[optic] = ratingText(
report({ at: lanternAt(8), tilt: 0, mix: mixOf(optic), power: 1 }).rating,
);
}
return out;
})();
type Stats = {
zones: Record;
rating: Rating;
roadAvg: number;
roadPeak: number;
window: number;
};
/** A value that eases from where it is to a target. */
class Tween {
from: number;
to: number;
start = 0;
constructor(
public value: number,
public duration: number,
) {
this.from = value;
this.to = value;
}
set(to: number, now: number, instant = false) {
if (to === this.to && !instant) return;
this.from = instant ? to : this.value;
this.to = to;
this.start = now;
if (instant) this.value = to;
}
step(now: number) {
if (this.value === this.to) return false;
const t = clamp((now - this.start) / this.duration, 0, 1);
this.value = t >= 1 ? this.to : this.from + (this.to - this.from) * ease(t);
return true;
}
}
const lux = (value: number) =>
value < 0.05 ? '0' : value < 10 ? value.toFixed(1) : Math.round(value).toString();
const pct = (value: number) => `${Math.round(value * 100)}%`;
export function StreetLight({
defaultOptic = 'asymmetric',
defaultHeight = 8,
defaultTilt = 0,
defaultLuxMap = false,
onChange,
autoplay = true,
colorScheme,
className = '',
}: {
/** The optic in the head when it mounts. */
defaultOptic?: Optic;
/** The pole's height, metres (5 to 12). */
defaultHeight?: number;
/** The head's tilt towards the houses, degrees (0 to 25). */
defaultTilt?: number;
/** Starts with the lux map on. */
defaultLuxMap?: boolean;
/** Called with the settings whenever the reader (or the demo) changes them. */
onChange?: (settings: { optic: Optic; height: number; tilt: number; luxMap: boolean }) => void;
/** While on screen and untouched, a demo pointer plays with the controls. */
autoplay?: boolean;
/** Light or dark colours, or the reader's ('system'); without it, the page's color-scheme. */
colorScheme?: 'light' | 'dark' | 'system';
className?: string;
}) {
const { ref: root, playing, take } = useAutoplay(6000);
const [optic, setOptic] = useState(defaultOptic);
const [height, setHeight] = useState(clamp(defaultHeight, HEIGHT.min, HEIGHT.max));
const [tilt, setTilt] = useState(clamp(defaultTilt, TILT.min, TILT.max));
const [luxMap, setLuxMap] = useState(defaultLuxMap);
const [stats, setStats] = useState(null);
const [spoken, setSpoken] = useState('');
const canvas = useRef(null);
const figure = useRef(null);
const probe = useRef(null);
const pointer = useRef(null);
const heightInput = useRef(null);
const tiltInput = useRef(null);
const cards = useRef>({
narrow: null,
wide: null,
asymmetric: null,
});
const luxButton = useRef(null);
const id = useId();
/** What the paint loop reads: the settings, and the eased values. */
const live = useRef({ optic, height, tilt, luxMap });
live.current = { optic, height, tilt, luxMap };
const kick = useRef<() => void>(() => {});
const demo = autoplay && playing;
useEffect(() => {
onChange?.({ optic, height, tilt, luxMap });
kick.current();
// onChange is the caller's: only the settings trigger it.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [optic, height, tilt, luxMap]);
// The paint loop: runs while something eases, idles otherwise.
useEffect(() => {
const element = canvas.current;
const box = figure.current;
const scheme = probe.current;
if (!element || !box || !scheme) return;
const renderer = new Renderer(element);
const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
const start = live.current;
const mix = Object.fromEntries(
OPTICS.map((o) => [o, new Tween(o === start.optic ? 1 : 0, 1100)]),
) as Record;
const lift = Object.fromEntries(
OPTICS.map((o) => [o, new Tween(o === start.optic ? 1 : 0, 450)]),
) as Record;
const map = new Tween(start.luxMap ? 1 : 0, 800);
const power = new Tween(reduced ? 1 : 0, 1100);
let switchedOn = reduced;
let frame = 0;
let dirty = true;
let last = { key: '', stats: null as Stats | null };
const readScheme = () => {
const dark = getComputedStyle(scheme).color.replace(/\s/g, '') === 'rgb(255,255,255)';
const palette = dark ? PALETTES.dark : PALETTES.light;
if (renderer.palette !== palette) {
renderer.palette = palette;
renderer.invalidate();
dirty = true;
}
};
const tick = (now: number) => {
frame = 0;
const s = live.current;
for (const o of OPTICS) {
mix[o].set(o === s.optic ? 1 : 0, now, reduced);
lift[o].set(o === s.optic ? 1 : 0, now, reduced);
}
map.set(s.luxMap ? 1 : 0, now, reduced);
let moving = false;
for (const t of [...Object.values(mix), ...Object.values(lift), map, power]) {
if (t.step(now)) moving = true;
}
if (moving || dirty) {
dirty = false;
const m: Mix = {
narrow: mix.narrow.value,
wide: mix.wide.value,
asymmetric: mix.asymmetric.value,
};
const lantern: Lantern = {
at: lanternAt(s.height),
tilt: rad(s.tilt),
mix: m,
power: power.value,
};
const key = `${s.height}|${s.tilt}|${m.narrow}|${m.wide}|${m.asymmetric}`;
const rep = report(lantern);
const layout = build(s.height, rad(s.tilt), s.optic, {
narrow: lift.narrow.value,
wide: lift.wide.value,
asymmetric: lift.asymmetric.value,
});
const head = headPoints(s.height, rad(s.tilt));
renderer.paint(
layout,
{ lantern, map: map.value, sky: rep.zones.sky, houses: rep.zones.houses },
head.lens,
);
const ground = renderer.stats(lantern, WINDOW);
const next: Stats = { zones: rep.zones, rating: rep.rating, ...ground };
const statsKey = `${key}|${power.value.toFixed(3)}`;
if (statsKey !== last.key) {
last = { key: statsKey, stats: next };
setStats(next);
}
}
if (moving) frame = requestAnimationFrame(tick);
};
const request = () => {
if (!frame) frame = requestAnimationFrame(tick);
};
kick.current = () => {
dirty = true;
request();
};
const resize = () => {
const { width, height: h } = element.getBoundingClientRect();
if (width > 0 && h > 0) renderer.resize(width, h);
dirty = true;
request();
};
const observer = new ResizeObserver(resize);
observer.observe(element);
resize();
readScheme();
// The lamp comes on once the figure is first seen.
const seen = new IntersectionObserver(
([entry]) => {
if (!entry.isIntersecting || switchedOn) return;
switchedOn = true;
window.setTimeout(() => {
power.set(1, performance.now());
request();
}, 350);
},
{ threshold: 0.3 },
);
seen.observe(box);
// A change of colour scheme ends the probe's transition: repaint then.
const onScheme = () => {
readScheme();
request();
};
scheme.addEventListener('transitionend', onScheme);
const media = window.matchMedia('(prefers-color-scheme: dark)');
media.addEventListener('change', onScheme);
return () => {
cancelAnimationFrame(frame);
observer.disconnect();
seen.disconnect();
scheme.removeEventListener('transitionend', onScheme);
media.removeEventListener('change', onScheme);
kick.current = () => {};
};
}, []);
// What screen readers hear: the summary line, once the settings rest.
const summary = stats
? `${ratingText(stats.rating)} · road ${pct(stats.zones.road)} · sky ${pct(stats.zones.sky)} · window ${stats.window.toFixed(1)} lx`
: '';
useEffect(() => {
const timer = window.setTimeout(() => setSpoken(summary), 600);
return () => window.clearTimeout(timer);
}, [summary]);
// Dragging on the figure: up and down for the height, left and right for the tilt.
const drag = useRef<{ x: number; y: number; height: number; tilt: number; id: number } | null>(
null,
);
const onPointerDown = (event: ReactPointerEvent) => {
if (event.button !== 0) return;
take();
drag.current = { x: event.clientX, y: event.clientY, height, tilt, id: event.pointerId };
event.currentTarget.setPointerCapture(event.pointerId);
};
const onPointerMove = (event: ReactPointerEvent) => {
const d = drag.current;
if (!d || d.id !== event.pointerId) return;
const scale = 320 / Math.max(240, event.currentTarget.offsetWidth);
const h = d.height - (event.clientY - d.y) * 0.025 * scale;
const t = d.tilt + (event.clientX - d.x) * 0.06 * scale;
setHeight(Math.round(clamp(h, HEIGHT.min, HEIGHT.max) * 10) / 10);
setTilt(Math.round(clamp(t, TILT.min, TILT.max) * 10) / 10);
};
const onPointerUp = (event: ReactPointerEvent) => {
if (drag.current?.id === event.pointerId) drag.current = null;
};
// Any real input hands the component to the reader; keys 1 to 3 and L work anywhere in it.
const onInput = useEffectEvent((event: Event) => {
if (event instanceof PointerEvent && !event.isPrimary) return;
take();
if (!(event instanceof KeyboardEvent)) return;
if (event.metaKey || event.ctrlKey || event.altKey) return;
const index = ['1', '2', '3'].indexOf(event.key);
if (index >= 0) {
setOptic(OPTICS[index]);
event.preventDefault();
} else if (event.key === 'l' || event.key === 'L') {
setLuxMap((on) => !on);
event.preventDefault();
}
});
useEffect(() => {
const element = root.current;
if (!element) return;
const listen = (event: Event) => onInput(event);
const options = { capture: true, passive: false };
element.addEventListener('pointerdown', listen, options);
element.addEventListener('wheel', listen, { capture: true, passive: true });
element.addEventListener('keydown', listen, options);
return () => {
element.removeEventListener('pointerdown', listen, options);
element.removeEventListener('wheel', listen, { capture: true });
element.removeEventListener('keydown', listen, options);
};
}, [root]);
// The demo: a pointer that plays with the controls, as a reader would.
const script = useEffectEvent(() => {
const stage = root.current;
const arrow = pointer.current;
if (!stage || !arrow) return () => {};
const at = (element: Element | null, fx = 0.5, fy = 0.5): Point => {
if (!element) return { x: 0, y: 0 };
const s = stage.getBoundingClientRect();
const r = element.getBoundingClientRect();
return { x: r.left - s.left + r.width * fx, y: r.top - s.top + r.height * fy };
};
/** Where a slider's thumb is for a value, in the stage's px. */
const thumb = (input: HTMLInputElement | null, value: number, min: number, max: number) => {
if (!input) return { x: 0, y: 0 };
const s = stage.getBoundingClientRect();
const r = input.getBoundingClientRect();
const size = 14;
return {
x: r.left - s.left + size / 2 + ((value - min) / (max - min)) * (r.width - size),
y: r.top - s.top + r.height / 2,
};
};
let current = { height: live.current.height, tilt: live.current.tilt };
return runDemo(stage, arrow, async ({ wait, glide, glyph }) => {
/** Drags a slider from its value to `to`, the pointer and the value moving together. */
const slide = async (which: 'height' | 'tilt', to: number, ms: number) => {
const input = which === 'height' ? heightInput.current : tiltInput.current;
const range = which === 'height' ? HEIGHT : TILT;
const from = current[which];
const set = which === 'height' ? setHeight : setTilt;
let raf = 0;
const t0 = performance.now();
const run = () => {
const t = clamp((performance.now() - t0) / ms, 0, 1);
const e = t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
set(Math.round((from + (to - from) * e) * 10) / 10);
if (t < 1) raf = requestAnimationFrame(run);
};
raf = requestAnimationFrame(run);
try {
await glide(thumb(input, to, range.min, range.max), ms);
} finally {
cancelAnimationFrame(raf);
}
set(to);
current = { ...current, [which]: to };
};
const press = async (element: Element | null, act: () => void) => {
await glide(at(element, 0.62, 0.62), 900);
glyph('hand');
await wait(260);
act();
await wait(380);
glyph('arrow');
};
const grab = async (which: 'height' | 'tilt') => {
const input = which === 'height' ? heightInput.current : tiltInput.current;
const range = which === 'height' ? HEIGHT : TILT;
await glide(thumb(input, current[which], range.min, range.max), 850);
await wait(250);
};
await wait(1500);
for (;;) {
current = { height: live.current.height, tilt: live.current.tilt };
await press(cards.current.wide, () => setOptic('wide'));
await wait(1500);
await grab('tilt');
await slide('tilt', 15, 1500);
await wait(700);
await press(luxButton.current, () => setLuxMap(true));
await wait(1900);
await press(cards.current.narrow, () => setOptic('narrow'));
await wait(1700);
await grab('tilt');
await slide('tilt', 0, 1300);
await wait(600);
await press(cards.current.asymmetric, () => setOptic('asymmetric'));
await wait(1500);
await grab('height');
await slide('height', 6.6, 900);
await wait(250);
await slide('height', 11.5, 1500);
await wait(350);
await slide('height', 8, 1000);
await wait(700);
await press(luxButton.current, () => setLuxMap(false));
await wait(2400);
}
});
});
useEffect(() => {
if (!demo) return;
return script();
}, [demo]);
const zones = stats?.zones;
return (