Skip to content

Fire

Warm flames and sparks rise from the visible shape.

Live preview needs JavaScript and WebGPU.

Category
Energy
Function
attachFire
Options
FireOptions
Package
@domfx/browser

Usage

attachFire(target: Element, options: FireOptions): FireEffectHandle

Returns an effect instance immediately. Imports are safe during server rendering; call the function in the browser after the elements are mounted. The Standalone guide includes the required HTML and CSS.

import { attachFire } from '@domfx/browser';
import type { FireOptions } from '@domfx/browser';

// Run after mount; host contains target and has position: relative.
const options: FireOptions = {
  host, clock: 'auto', intensity: 0.8,
  flameReach: 0.2,
  emberDensity: 1,
};
const effect = attachFire(target, options);
// Also call effect.dispose() on component unmount.
window.addEventListener('pagehide', () => effect.dispose(), { once: true });
await effect.ready;
if (effect.lifecycle !== 'active') {
  console.info(effect.reason, effect.reasonDetail);
}

Effect options

FireOptions extends AttachmentOptions with two mutually exclusive geometry creation options.

PropertyTypeDefault
flameReach

Finite nonnegative fraction of the untransformed target border-box height, including transparent margins. 0.1 means 10 CSS px on a 100 px target and 40 px on a 400 px target. Bounds exterior distance and upward travel; it does not guarantee a visible tip in every frame. Intensity changes strength independently of reach and fine detail. Zero produces transparent output. Creation-only; resolved again on capture after resize.

numberOmitted (Default appearance)
PropertyType and rangeDefault
emberDensity

Selects fixed seeded ember sites without moving survivors or changing their glow. This is a creation option: use a new instance to change it. The instance exposes the resolved value as read-only.

number · 0–11

Root color and Tip color run from the base of the flame to its ends. They are also writable instance properties, and replace the authored three-stop palette with a two-color blend. They cannot be combined with color: creating Fire with both, or writing one while the other is set, throws invalid-fire-parameter and keeps the prior value. To switch, assign undefined first.

PropertyTypeWhen unset
rootColor

Color at the base of the flame. Same format as color: hex, rgb() or opaque rgba(). The getter returns normalized rgb(...), or undefined when unset.

string#fff5a3
tipColor

Color at the ends of the flame and of the embers. With either color set, embers use this color or its default; with neither, they keep #ffc747.

string#ff1701

Either color can be set alone; the other uses its default. With neither set, output is unchanged. The blend position includes flame density, so it runs from base to ends rather than following an exact height. Writing these colors keeps the capture, geometry and GPU resources.

Shared options

Use the exported AttachmentOptions type. Only host is required. Every effect except Burned paper extends it with ColorAttachmentOptions.

PropertyTypeDefault
host

The effect container: an HTML element already on the page, with CSS position other than static. It must contain the target in the same document; it cannot be the target itself.

HTMLElementRequired
clock

Use manual for your code or GSAP to control time; auto advances time automatically.

'manual' | 'auto''manual'
motion

respect suppresses output under reduced motion. static always renders a still effect at time zero, under either preference.

'respect' | 'static''respect'
seed

Fixed random seed. Keeps the pattern repeatable for the same time, settings and captured target. It does not set the amount of randomness or guarantee identical pixels across devices.

number0
time

Initial effect time in seconds. Negative values are accepted.

number0
intensity

Initial effect strength. Accepted values clamp to 0–1; the visual response depends on the effect.

number1
color

Optional main decorative color for every effect except Burned paper. Accepts #RGB, #RRGGBB, rgb(...) and rgba(..., 1). Omit it to keep the effect’s original colors; assign undefined to restore them.

string | undefinedOmitted (original colors)

All numeric values must be finite. time, seed, intensity and creation-only controls must fit float32. Writable artistic controls, including their initial values, accept any finite number and clamp to 0–1; invalid values for other options throw before clamping. To change a creation option other than time or intensity, dispose the attachment and create a replacement.

Only one effect can use a target at a time. Invalid host relationships and overlapping targets throw synchronously. Dispose the existing effect before attaching to the same target, its ancestor or a descendant. This restriction describes the element tree, not arbitrary visual overlap.

Controls

With flameReach, scales visual strength without changing reach or fine detail. Omitted flameReach keeps the Default appearance, where intensity also changes flame reach.

Read and write these properties on the effect instance. Writes are immediately readable. When output is available, they render on the next frame without recapturing the target.

PropertyType
time

Effect time in seconds. Supports forward and backward seeking, including negative time.

number
intensity

Effect strength, clamped to 0–1 after validation. It is not a universal height or opacity setting.

number
color

Optional main decorative color. Every effect except Burned paper supports it; assign undefined to restore the original colors.

string | undefined

All numeric values must be finite. time and intensity must fit float32. intensity and effect-specific controls clamp to 0–1; the latter accept any finite number. An invalid assignment throws and preserves the previous value. Use one writer per property: direct assignments, a timeline or another animation driver.

See automatic animation and external control and the GSAP guide. The effect instance reference documents state, capture updates and cleanup.

Limits

The effect follows the captured visible shape, including holes and disconnected regions. An opaque image has a rectangular shape. The decorative layer leaves the original content intact.

Only the listed options are public. Every effect except Burned paper permits one main decorative color; gradients, particle counts and whole-element processing are not configurable. Keep the original content usable when output is unavailable. For WebGPU, capture and composition limits, see browser support and troubleshooting.

rootColor and tipColor are the exception to one main color, with two fixed endpoints and no further stops. They blend in gamma-encoded sRGB, matching default CSS gradients and GSAP string tweens. Complementary pairs therefore pass through gray at their midpoint: #0066ff and #ff9900 average about #808080.

flameReach reserves symmetric padding independently of intensity: reach + 2 CSS px of paint overflow + a sampling guard of 2 CSS px and 2 raster pixels, rounded up with an 8 CSS px minimum. Requires contained descendant boxes and paint within the border box plus 2 CSS px; shadows, filters, outlines and generated pseudo-elements are unsupported. Every captured alpha sample is checked; insufficient margin reports missing-exterior. Existing one-million-pixel, memory and device-dimension limits can report capture-budget or another unavailable state; reach and quality are never silently reduced. Fractional raster mapping and DPR apply once; supported translation and positive scale change placement only.

Compare every effect side by side in the gallery.