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.
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.
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 for a complete setup.
Creation options
Section titled “Creation options”Choose the target’s container, animation control, reduced-motion behavior and initial values in the shared options reference.
Effect-specific options
Section titled “Effect-specific options”Fire’s flameReach 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 for its fields, paired zero defaults and finite support limits. Omitting all extents keeps the Default appearance.
Writable controls
Section titled “Writable controls”Set time and intensity 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”Inspect readiness, effect state and capture status. A completed setup attempt does not guarantee visible output.
Methods
Section titled “Methods”Pause, resume, refresh, retry and dispose have the same contract for every effect.
Available effects
Section titled “Available effects”Import these functions from @domfx/browser. Each reference opens with a live preview, followed by its exact options.
| Effect | Function | Category |
|---|---|---|
| Electricity | attachElectricity | Energy |
| Frost | attachFrost | Material |
| Fire | attachFire | Energy |
| Dither | attachDither | Pattern |
| Slime | attachSlime | Material |
| Kinetic bloom | attachKinetic | Energy |
| Burned paper | attachBurnedPaper | Material |
| Halftone | attachHalftone | Pattern |
| Stipple | attachStipple | Pattern |
| Scanlines | attachScanlines | Pattern |
| Crosshatch | attachCrosshatch | Pattern |
| Diamond lattice | attachDiamonds | Pattern |
| Contour echoes | attachContourEchoes | Pattern |
| Engraving | attachEngraving | Pattern |
| Woven mesh | attachWovenMesh | Pattern |
| Hexagons | attachHexagons | Pattern |
| Interference | attachInterference | Pattern |
| Shards | attachShards | Pattern |
| Circuits | attachCircuits | Pattern |
| Star shimmer | attachStarShimmer | Pattern |
| Brush fringe | attachBrushFringe | Pattern |
Use ordinary gsap.to() and timeline calls on an effect instance. The GSAP reference explains optional bindings that keep fixed starting values and manage cleanup.
Packages
Section titled “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.