# 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](/docs/installation/), then save the complete module below as `main.ts`.

## Attach Fire

[Section titled “Attach Fire”](#attach-fire)

`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.

```ts
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](#unavailable-output) below.

[Interactive effect lab: view the live page](https://domfx.dev/docs/standalone/)

## Use another effect

[Section titled “Use another effect”](#use-another-effect)

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](/docs/api/effects/) opens with the same live preview, and the [gallery](/effects/) compares them side by side.

## Control time and intensity

[Section titled “Control time and intensity”](#control-time-and-intensity)

`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](/docs/api/shared/#control-playback) 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.

## Refresh and cleanup

[Section titled “Refresh and cleanup”](#refresh-and-cleanup)

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](/docs/frameworks/).

## Unavailable output

[Section titled “Unavailable output”](#unavailable-output)

`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](/docs/troubleshooting/) for reason codes and recovery.
