# 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](/docs/api/effects/).

## Creation options

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

Use the exported `AttachmentOptions` type. Only host is required. Every effect except Burned paper extends it with `ColorAttachmentOptions`.

| Property                                                                                                                                                                                                       | Type                    | Default                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------- |
| `host` The 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                  |
| `clock` Use manual for your code or GSAP to control time; auto advances time automatically.                                                                                                                    | `'manual' \| 'auto'`    | `'manual'`                |
| `motion` respect suppresses output under reduced motion. static always renders a still effect at time zero, under either preference.                                                                           | `'respect' \| 'static'` | `'respect'`               |
| `seed` Fixed 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`                       |
| `time` Initial effect time in seconds. Negative values are accepted.                                                                                                                                           | `number`                | `0`                       |
| `intensity` Initial effect strength. Accepted values clamp to 0–1; the visual response depends on the effect.                                                                                                  | `number`                | `1`                       |
| `color` Optional 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”](#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                  |
| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `time` Effect time in seconds. Supports forward and backward seeking, including negative time.                                         | `number`              |
| `intensity` Effect strength, clamped to 0–1 after validation. It is not a universal height or opacity setting.                         | `number`              |
| `color` Optional 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”](#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”](#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](/docs/api/effect-handle/) for readiness, pause/resume, refresh, retry and cleanup.
