Jack-o'-Lantern Light

Quick Start

1. Add to your HTML <head>:

Code snippet omitted: it ships with the download.

2. Add before the closing </body> tag. three.js loads as an ES module through an import map; the small module script then loads the effect, and loads it anyway if three.js fails, so the light still runs with the photograph.

Code snippet omitted: it ships with the download.

Already using three.js as a module on your page? Assign it to window.THREE before script.js runs and drop the import map. Want only the photographic lantern? Leave three.js out entirely and load script.js with a plain <script> tag; or set data-three="false".

3. Wrap the content to be lit, and put the lantern inside it:

Code snippet omitted: it ships with the download.

The lantern can sit anywhere inside [data-lantern-light]: where it renders is where it rests. In the demo it sits in an empty grid cell among the products.

Using It With Your Own Design

What the effect needs from your markup:

• [data-lantern-light]: the area that is lit. Everything inside it is in moonlight except where the candle reaches. The script adds its light and shadow layers inside this element.
• [data-lantern]: the lantern, which should be a <button> so it is focusable and toggles with Enter and Space. Give it an aria-label and, ideally, an aria-describedby that explains it can be moved with the arrow keys.
• [data-lantern-body]: a wrapper inside the button holding the images. It is what lifts, swings and squashes; the contact shadow and floor glow stay on the ground beneath it.
• data-lantern-depthmap on the button: the depth map for the 3D lantern (assets/img/lantern-depth.webp, white is nearest). Without it the photograph stays flat. The script adds a .lantern-canvas inside the button, sized to the button plus room to swing, and uses the images below as its textures; they also give the button its size and are the fallback.
• [data-lantern-img="lit"] is required. unlit (shown when the candle is out), glow (the carving running hot) and bloom (the halo) are optional; leave any out and that part simply does not happen.
• data-lantern-origin="x y": where the flame is, as percentages of the lantern image. 55.6 63.2 is right for the bundled photograph; change it if you swap the image. The 3D lantern uses the same resting point and moves the light from there as the pumpkin swings.
• [data-lantern-lit]: any raised element that should cast a shadow. Give one a different height with data-lantern-depth (pixels; 0 turns its shadow off). Unmarked content is still lit; it just casts no shadow.
• [data-lantern-cue] (optional): a hint that fades out the first time the lantern is moved.

What is only the demo's styling: the whole shop: the grid, cards, type, palette, the intro copy and the product photographs. Replace it wholesale. The cue pill's look is demo styling too.

CSS the effect depends on (all under "Effect layers" in style.css):

• [data-lantern-light] needs position: relative, isolation: isolate and overflow: hidden. Isolation keeps the light's blend modes inside the section; without it they would blend with the rest of your page.
• The moonlight is the ::after of [data-lantern-light] under .has-js. Its colour is --lantern-moon (default rgb(66, 70, 88)): lighter is a brighter night, bluer is colder.
• Lay the lit area out in mid-tones, not near-black. The light reveals what is there, so a black ground has nothing for it to reveal and nothing for shadows to fall on. The demo uses a warm mid-brown ground (--lit-page) and slightly lighter cards (--lit-surface) under .has-js, and keeps dark colours for the no-JavaScript page. Check text contrast against these mid-tones.
• .lantern-map, .lantern-air, .lantern-shadows, .lantern-shadow*, .lantern-contact, .lantern-spill and .lantern-smoke style the generated layers. Keep their positioning, blend modes and will-change; the shadow plates' colours and softness can be tuned.
• [data-lantern] needs a z-index above the light layers (it is the source, so it is never dimmed) and touch-action: none so a touch drag moves the lantern instead of scrolling the page. Size it with width.
• .is-live [data-lantern-img] { visibility: hidden } hides the flat photograph once the 3D lantern has drawn, without collapsing the button. Both draw the same pixels at rest, so the swap is invisible. .lantern-canvas must stay position: absolute and pointer-events: none.
• .has-js [data-lantern-img='lit'] { opacity: 0 } lets the page open in moonlight before the candle is struck. Without JavaScript the class is never added and the lit lantern shows.

Options

Set these on [data-lantern-light].

On [data-lantern-lit]: data-lantern-depth overrides the default height for that element.

Accessibility

• Keyboard: the lantern is a real <button> with aria-pressed reflecting whether the candle is lit. Arrow keys move it (Shift for bigger steps), Enter or Space blows the candle out or relights it. Focusing it gives a gentle flare so the focused state is visible beyond the focus ring.
• Touch: drag the lantern with a finger; a tap toggles the candle. Only the lantern captures touch, so the rest of the page scrolls normally.
• Reduced motion: the pumpkin stays a flat photograph, the flicker becomes a slow, gentle breath, the lantern moves without swing or squash, and the candle fades out and back in without the gutter, smoke or flare. The light and shadows still follow the lantern.
• Readable content: the light and shadows are visual layers only. Text stays in the DOM, and even the furthest content stays legible in the moonlight. The demo's colours meet contrast against the page's own surfaces.
• No JavaScript: the moonlight is never applied, the content shows at full brightness and the lit photographic pumpkin sits in its place.
• No WebGL or no three.js: the flat photograph is used, with the same light, shadows, drag, keyboard and candle.

Performance

• Per frame the script writes only transforms and opacities, on layers that were drawn once. The light map is drawn small and scaled up, and the shadow plates are softened once when they are created, so the flicker never re-rasterises a blur.
• The 3D canvas is only the lantern's box plus room to swing, with the pixel ratio capped at 1.5. While nothing moves it redraws the flicker at about 30 fps; while the pumpkin turns, swings or is carried it draws every frame. The page's light layers update at up to 60 fps when idle.
• Measured in headless Chrome on an Apple M1 Pro GPU at 1440×900, DPR 2 (main-thread time per 5 seconds): lit and idle about 0.18 s (0.16 s with data-three="false"), dragging continuously about 0.55 s, candle out 0 to 0.02 s, off screen about 0.02 s.
• Everything stops when the section is off screen, when the tab is hidden and while the candle is out and nothing is moving.
• The first lever to lower: data-three="false" (photographic lantern, no WebGL at all), then data-flicker="0".

Browser Support

The 3D form needs WebGL and ES module support (every current browser). The script probes WebGL before creating a renderer, and handles a lost context by falling back to the photograph until the context is restored.

Images

The pumpkin is a photograph by Mátyás Varga on Pexels (Illuminated Carved Pumpkin), used under the Pexels licence. The bundled files in assets/img/ are cut-out, art-directed derivatives: the lit pumpkin, a candle-out version, the carving on its own, its halo, and a depth map hand-built from the cut-out (an ellipsoid bulge from the distance to its edge, faint relief from the photo's own light, and the stem set on the body).

The product photographs (pendant lamps, stoneware bowls, lounge chair, candle table and cane chair) are Pexels photographs baked to graded WebP derivatives. They are demo content; replace them with your own.

To use your own lantern, cut it out on a transparent background, export the lit version, and set data-lantern-origin to the flame's position. The unlit, glow and bloom layers are optional extras. For 3D form, supply a greyscale depth map of the same framing (white nearest, black at the silhouette, softly rounded); a depth estimation model's output works, or a blurred, rounded version of the cut-out's alpha. Keep it smooth: sharp steps tear the photo when it turns.

Dependencies

No GSAP plugins.