Fold.page · HDRI Environment · JavaScript API

Image-Based Lighting

HDR environment configured entirely through Fold.init()

The night sky as a light source

The model above is lit entirely by the Rogland night sky HDR. No manual point lights or directionals were added. Every highlight, shadow, and tonal variation on the mesh comes from the equirectangular sky image wrapped around the scene — the ambient star glow and horizon gradient provide the light energy that PBR materials respond to.

Internally, Fold passes the loaded .hdr through Three.js's PMREMGenerator, which pre-filters the environment into a cubemap optimised for physically-based rendering. The result is set as scene.environment — and all MeshStandardMaterial and MeshPhysicalMaterial meshes in the scene automatically pick it up as their ambient light source, with no extra wiring required.

background

Decouple lighting from the visible sky

IBL lighting is always active once src is set. The visible sky background is independent and optional — the background field controls where, if anywhere, it appears.

false (default)

IBL lighting only. No visible sky — your HTML page background colour shows instead. Ideal when you want environment-quality lighting without the 360° sky effect.

true / 'both'

Sky visible everywhere — on screen and in XR. This demo uses true. The night sky wraps the full scene in both contexts.

'screen'

Sky visible on screen only. In XR the background is transparent so the real world shows through for AR passthrough.

'xr'

Sky visible in XR only. On screen, IBL lights your models but your HTML background colour fills the canvas.

Fold.init() — complete HDR configuration

All HDR options are passed as a single hdr object to Fold.init(). No DOM attribute or hidden element needed.

Fold.init({
  // Standard Fold.init options
  foldpage:         true,

  loadingIndicator: false,

  // ── HDRI Environment ─────────────────────────────────────────
  hdr: {
    // Path to an equirectangular .hdr file
    src: '/demos/hdr/rogland_clear_night_2k.hdr',

    // Where the sky renders as a visible background.
    // false       → IBL only, no sky (default)
    // true/'both' → visible on screen and in XR
    // 'screen'    → screen only (hides in XR passthrough)
    // 'xr'        → XR only (hides on screen)
    background: true,

    // IBL intensity — scales environment light strength on PBR materials
    intensity: 0.8,

    // Background blur 0–1  (0 = sharp sky, 1 = fully blurred)
    // Does not affect IBL quality — only the visible background.
    blur: 0,
  },
});

Parameter Reference

HDR options at a glance

Parameter	Default	Description
hdr.src	—	Path or URL to an equirectangular `.hdr` file. Activates IBL and optional background. Takes precedence over `data-{ns}-hdr-src` on the page when both are present. A plain string passed as `hdr` is equivalent to `{ src: '...' }`.
hdr.background	false	Controls the visible sky. `false` = IBL only. `true` / `'both'` = visible everywhere. `'screen'` = screen only. `'xr'` = XR only.
hdr.intensity	1.0	Scales IBL strength on all PBR materials in the scene. Does not affect background brightness — only the light contribution from the environment map.
hdr.blur	0	Background blur from `0` (sharp) to `1` (fully blurred). Only applies when the background is visible. IBL cubemap quality is unaffected.

Fold.init() vs Data Attributes

Two equivalent APIs

Both approaches produce an identical result. Fold.init() is the right choice when you compute the HDR path at runtime, load it from a CMS, or want all configuration in one place. Data attributes are better for static HTML pages where you want zero JavaScript beyond the Fold.init() call itself.

When both are present on the same page, Fold.init() takes precedence and the data-foldpage-hdr-src element is silently ignored.

See the data-attribute HDRI demo → for the equivalent scene set up with a single hidden element and no HDR parameters in JavaScript.