Skip to content

Standalone

Attach an effect, control its animation and tune a live Fire example.

Add animated flames to a button while keeping its interaction. Create the files in the installation guide, then save the complete module below as main.ts.

clock: ‘auto’ advances effect time automatically. Cleanup is registered before waiting for fonts and preparing Fire, so leaving during loading cannot create a late effect.

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

const host = document.querySelector('#host');
const target = document.querySelector('#target');
const clicks = document.querySelector('#clicks');
if (!(host instanceof HTMLElement) || !target || !clicks) {
  throw new Error('Missing host, target or click counter');
}

let count = 0;
const onClick = () => { clicks.textContent = String(++count); };
target.addEventListener('click', onClick);

let disposed = false;
let fire: ReturnType<typeof attachFire> | undefined;

function cleanup() {
  disposed = true;
  window.removeEventListener('pagehide', cleanup);
  target?.removeEventListener('click', onClick);
  fire?.dispose();
}

// Before calling setup, also register cleanup to run on component unmount.
window.addEventListener('pagehide', cleanup, { once: true });

const setup = async () => {
  await document.fonts.ready;
  if (disposed) { return; }

  fire = attachFire(target, {
    host, clock: 'auto', motion: 'respect',
    intensity: 0.8, seed: 314,
  });
  await fire.ready;
  if (!disposed && fire.lifecycle !== 'active') {
    console.info(fire.reason);
  }
};

void setup();

Run pnpm dev and open the printed loopback URL. Flames surround the button; clicking it increases the counter. To try the production build, run pnpm build, then pnpm preview.

If the effect is unavailable, the button still works. Check the console reason and Unavailable output below.

Tune the attachment

Flame reach is a fraction of the target's height. Changing it recreates the effect; intensity changes strength. The original text remains selectable.

domfx

Live preview needs JavaScript and WebGPU.

Replace attachFire with an attachment such as attachFrost or attachDither and use that effect’s creation options. flameReach is Fire-only. Time, intensity and instance methods are shared; intensity follows the chosen effect and sizing mode.

Dispose the existing attachment before attaching another effect to the same target. Every effect reference opens with the same live preview, and the gallery compares them side by side.

fire.pause() pauses automatic animation. fire.resume() continues without catching up time spent paused or hidden. Set fire.intensity to a value between 0 and 1. See the control reference for accepted values.

For explicit seeking, choose clock: ‘manual’ at creation and write fire.time in absolute seconds. Forward and backward seeks reuse the capture. With external control, paused stays true even while time changes; resume() does not advance it.

After changing captured paint, await fire.refresh(). It hides stale output and resolves once this or a newer requested capture is accepted. Observed target mutations and resize can refresh automatically; unobserved stylesheet, hover or ancestor paint changes still need explicit refresh.

Refreshing recaptures the target’s appearance without bypassing image caching. For changing image content, use versioned URLs or server cache headers that require revalidation.

Call cleanup() on component unmount; pagehide only covers leaving the page. It is safe to call more than once, including while fonts or ready are pending. Register it synchronously in your framework’s teardown hook before calling setup(). On remount, run the module’s setup and ownership code again with fresh variables and elements; a disposed effect cannot be reused. In React or Vue, copy the tested recipes.

ready resolves after an attempt, including environmental unavailability. Inspect fire.lifecycle, fire.raster and fire.reason. Keep the original content available. After correcting the condition, explicitly await fire.retry() and inspect the result again.

The default motion: ‘respect’ suppresses output under reduced motion. Changing the preference back requires an explicit retry. motion: ‘static’ opts into a still decoration at time zero; it never overrides reduced motion with animation.

See troubleshooting for reason codes and recovery.