# API reference

Options, properties and methods shared by every effect.

All 21 effects accept shared creation options and return an effect instance (`EffectHandle`). Start with an effect’s reference for its import, appearance and supported options.

## Usage

[Section titled “Usage”](#usage)

Import an attachment function from `@domfx/browser`. Call it in the browser after mounting the target element and its effect container (`host`). The container must contain the target and have CSS `position` other than `static`. Imports are SSR-safe; attachment and capture require browser DOM elements.

```ts
import { attachFrost } from '@domfx/browser';
import type { AttachmentOptions } from '@domfx/browser';

const options: AttachmentOptions = {
host,
clock: 'manual',
intensity: 0.8,
};
const effect = attachFrost(target, options);

// Also dispose on component unmount.
window.addEventListener('pagehide', () => effect.dispose(), { once: true });
await effect.ready;
if (effect.lifecycle === 'active') {
effect.time = 2;
}
```

Each attachment takes `(target: Element, options)` and immediately returns an `EffectHandle`. See the [Standalone guide](/docs/standalone/) for a complete setup.

## Creation options

[Section titled “Creation options”](#creation-options)

Choose the target’s container, animation control, reduced-motion behavior and initial values in the [shared options reference](/docs/api/shared/#attachment-options).

### Effect-specific options

[Section titled “Effect-specific options”](#effect-specific-options)

[Fire’s `flameReach`](/docs/api/effects/fire/#effect-options) is a creation option that sets reach relative to target height. Omit it for the Default appearance.

All 21 effects have effect-owned, creation-only relative extent options. Directional travel uses physical target height; inward depth and radial travel use the shorter untransformed border-box side. Transparent margins count; capture padding does not. Supplying an extent enables strength-only intensity in that mode. See each [effect reference](/docs/api/effects/) for its fields, paired zero defaults and finite support limits. Omitting all extents keeps the Default appearance.

## Writable controls

[Section titled “Writable controls”](#writable-controls)

Set [time and intensity](/docs/api/shared/#control-playback) directly or through GSAP. Time is in seconds; intensity is an effect-specific strength from 0 to 1.

## Read-only state

[Section titled “Read-only state”](#read-only-state)

Inspect [readiness, effect state and capture status](/docs/api/effect-handle/#read-state). A completed setup attempt does not guarantee visible output.

## Methods

[Section titled “Methods”](#methods)

[Pause, resume, refresh, retry and dispose](/docs/api/effect-handle/#refresh-retry-and-dispose) have the same contract for every effect.

## Available effects

[Section titled “Available effects”](#available-effects)

Import these functions from `@domfx/browser`. Each reference opens with a live preview, followed by its exact options.

| Effect                                              | Function              | Category |
| --------------------------------------------------- | --------------------- | -------- |
| [Electricity](/docs/api/effects/electricity/)       | `attachElectricity`   | Energy   |
| [Frost](/docs/api/effects/frost/)                   | `attachFrost`         | Material |
| [Fire](/docs/api/effects/fire/)                     | `attachFire`          | Energy   |
| [Dither](/docs/api/effects/dither/)                 | `attachDither`        | Pattern  |
| [Slime](/docs/api/effects/slime/)                   | `attachSlime`         | Material |
| [Kinetic bloom](/docs/api/effects/kinetic/)         | `attachKinetic`       | Energy   |
| [Burned paper](/docs/api/effects/burned-paper/)     | `attachBurnedPaper`   | Material |
| [Halftone](/docs/api/effects/halftone/)             | `attachHalftone`      | Pattern  |
| [Stipple](/docs/api/effects/stipple/)               | `attachStipple`       | Pattern  |
| [Scanlines](/docs/api/effects/scanlines/)           | `attachScanlines`     | Pattern  |
| [Crosshatch](/docs/api/effects/crosshatch/)         | `attachCrosshatch`    | Pattern  |
| [Diamond lattice](/docs/api/effects/diamonds/)      | `attachDiamonds`      | Pattern  |
| [Contour echoes](/docs/api/effects/contour-echoes/) | `attachContourEchoes` | Pattern  |
| [Engraving](/docs/api/effects/engraving/)           | `attachEngraving`     | Pattern  |
| [Woven mesh](/docs/api/effects/woven-mesh/)         | `attachWovenMesh`     | Pattern  |
| [Hexagons](/docs/api/effects/hexagons/)             | `attachHexagons`      | Pattern  |
| [Interference](/docs/api/effects/interference/)     | `attachInterference`  | Pattern  |
| [Shards](/docs/api/effects/shards/)                 | `attachShards`        | Pattern  |
| [Circuits](/docs/api/effects/circuits/)             | `attachCircuits`      | Pattern  |
| [Star shimmer](/docs/api/effects/star-shimmer/)     | `attachStarShimmer`   | Pattern  |
| [Brush fringe](/docs/api/effects/brush-fringe/)     | `attachBrushFringe`   | Pattern  |

## GSAP

[Section titled “GSAP”](#gsap)

Use ordinary `gsap.to()` and timeline calls on an effect instance. The [GSAP reference](/docs/api/gsap/) explains optional bindings that keep fixed starting values and manage cleanup.

## Packages

[Section titled “Packages”](#packages)

| Package          | Responsibility                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `@domfx/core`    | Shared effect types, independent of DOM, GPU and frameworks. Installed automatically.       |
| `@domfx/browser` | Captures the target and renders its decorative effect. No consumer shader plugin is needed. |
| `@domfx/gsap`    | Optional binding to a caller-owned GSAP timeline. Standalone attachments do not load GSAP.  |

For local debugging, see [experimental attachment traces](/docs/troubleshooting/#trace-an-attachment).
