Skip to content

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.

Choose the target’s container, animation control, reduced-motion behavior and initial values in the shared options reference.

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.

Set time and intensity directly or through GSAP. Time is in seconds; intensity is an effect-specific strength from 0 to 1.

Inspect readiness, effect state and capture status. A completed setup attempt does not guarantee visible output.

Pause, resume, refresh, retry and dispose have the same contract for every effect.

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

EffectFunctionCategory
ElectricityattachElectricityEnergy
FrostattachFrostMaterial
FireattachFireEnergy
DitherattachDitherPattern
SlimeattachSlimeMaterial
Kinetic bloomattachKineticEnergy
Burned paperattachBurnedPaperMaterial
HalftoneattachHalftonePattern
StippleattachStipplePattern
ScanlinesattachScanlinesPattern
CrosshatchattachCrosshatchPattern
Diamond latticeattachDiamondsPattern
Contour echoesattachContourEchoesPattern
EngravingattachEngravingPattern
Woven meshattachWovenMeshPattern
HexagonsattachHexagonsPattern
InterferenceattachInterferencePattern
ShardsattachShardsPattern
CircuitsattachCircuitsPattern
Star shimmerattachStarShimmerPattern
Brush fringeattachBrushFringePattern

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.

PackageResponsibility
@domfx/coreShared effect types, independent of DOM, GPU and frameworks. Installed automatically.
@domfx/browserCaptures the target and renders its decorative effect. No consumer shader plugin is needed.
@domfx/gsapOptional binding to a caller-owned GSAP timeline. Standalone attachments do not load GSAP.

For local debugging, see experimental attachment traces.