Shared options and controls
Creation options and writable controls available on every effect.
Every effect accepts these creation options and returns the same EffectHandle. Effect-specific options belong to the individual effect references.
Creation options
Section titled “Creation options”Use the exported AttachmentOptions type. Only host is required. Every effect except Burned paper extends it with ColorAttachmentOptions.
| Property | Type | Default |
|---|---|---|
hostThe effect container: an HTML element already on the page, with CSS position other than static. It must contain the target in the same document; it cannot be the target itself. | HTMLElement | Required |
clockUse manual for your code or GSAP to control time; auto advances time automatically. | 'manual' | 'auto' | 'manual' |
motionrespect suppresses output under reduced motion. static always renders a still effect at time zero, under either preference. | 'respect' | 'static' | 'respect' |
seedFixed random seed. Keeps the pattern repeatable for the same time, settings and captured target. It does not set the amount of randomness or guarantee identical pixels across devices. | number | 0 |
timeInitial effect time in seconds. Negative values are accepted. | number | 0 |
intensityInitial effect strength. Accepted values clamp to 0–1; the visual response depends on the effect. | number | 1 |
colorOptional main decorative color for every effect except Burned paper. Accepts #RGB, #RRGGBB, rgb(...) and rgba(..., 1). Omit it to keep the effect’s original colors; assign undefined to restore them. | string | undefined | Omitted (original colors) |
All numeric values must be finite. time, seed, intensity and creation-only controls must fit float32. Writable artistic controls, including their initial values, accept any finite number and clamp to 0–1; invalid values for other options throw before clamping. To change a creation option other than time or intensity, dispose the attachment and create a replacement.
Only one effect can use a target at a time. Invalid host relationships and overlapping targets throw synchronously. Dispose the existing effect before attaching to the same target, its ancestor or a descendant. This restriction describes the element tree, not arbitrary visual overlap.
Writable controls
Section titled “Writable controls”Read and write these properties on the effect instance. Writes are immediately readable. When output is available, they render on the next frame without recapturing the target.
| Property | Type |
|---|---|
timeEffect time in seconds. Supports forward and backward seeking, including negative time. | number |
intensityEffect strength, clamped to 0–1 after validation. It is not a universal height or opacity setting. | number |
colorOptional main decorative color. Every effect except Burned paper supports it; assign undefined to restore the original colors. | string | undefined |
All numeric values must be finite. time and intensity must fit float32. intensity and effect-specific controls clamp to 0–1; the latter accept any finite number. An invalid assignment throws and preserves the previous value. Use one writer per property: direct assignments, a timeline or another animation driver.
Control animation
Section titled “Control animation”Use clock: ‘auto’ for automatic animation. domfx advances effect time while it can render, skipping time spent paused, hidden or offscreen.
Use clock: ‘manual’ for external control through your code or GSAP. domfx never advances time in this mode, including after resume(). It still observes the target and schedules rendering for the next frame.
time selects a point in the effect’s animation in seconds. It is neither progress from 0 to 1 nor elapsed wall-clock time. You can seek backward or use negative values. Let only one animation driver write each property.
Reduced motion
Section titled “Reduced motion”The default motion: ‘respect’ suppresses output when the user requests reduced motion. After the preference changes back, explicitly call retry(). It does not automatically replace animation with a still frame.
motion: ‘static’ always renders a still effect at time zero, under either preference. Time writes remain readable but do not change its rendered frame. Intensity and capture updates still work. resume() does not animate it.
See effect state and methods for readiness, pause/resume, refresh, retry and cleanup.