# Frost

A white-blue ice coating with pale smoke and small frost particles. Writable mistOpacity changes smoke opacity without changing the coating or grains.

[Interactive effect lab: view the live page](https://domfx.dev/docs/api/effects/frost/)

* Category

  [Material](/docs/api/effects/#material)

* Function

  `attachFrost`

* Options

  `FrostOptions`

* Package

  `@domfx/browser`

## Usage

`attachFrost(target: Element, options: FrostOptions): FrostEffectHandle`

Returns an effect instance immediately. Imports are safe during server rendering; call the function in the browser after the elements are mounted. The [Standalone guide](/docs/standalone/) includes the required HTML and CSS.

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

// Run after mount; host contains target and has position: relative.
const options: FrostOptions = {
  host, clock: 'auto', intensity: 0.8,
  coatingDepth: 0.1,
  mistReach: 0.2,
};
const effect = attachFrost(target, options);
// Also call effect.dispose() on component unmount.
window.addEventListener('pagehide', () => effect.dispose(), { once: true });
await effect.ready;
if (effect.lifecycle !== 'active') {
  console.info(effect.reason, effect.reasonDetail);
}
```

## Effect options

Creation options: finite nonnegative numeric fractions of the untransformed border box, excluding capture padding. Transparent margins count. Resolved again on capture after resize; supported translation and positive scale change placement only.

| Property                     | Type and unit                                 | Example     |
| ---------------------------- | --------------------------------------------- | ----------- |
| `coatingDepth` Coating depth | `number` · fraction of the shorter local side | `0.1` = 10% |
| `mistReach` Mist travel      | `number` · fraction of local physical height  | `0.2` = 20% |

Omitting both extents keeps the Default appearance. Supplying either enables relative mode: the missing partner is zero and disables that component. Intensity scales premultiplied output without changing geometry or fine detail. Both extents at zero produce transparent output. Changing an extent requires disposing and creating another instance; there are no geometric setters.

Depth bounds inward coverage; reach bounds mist, drip or ash travel. This is a permitted envelope, not a guaranteed visible tip. Grains, highlights and drops keep their local size. The material lip can extend up to 6 CSS px and moving marks up to 8 CSS px beyond travel; padding includes that support and the sampling guard.

Requires contained descendant boxes and paint within the border box plus 2 CSS px; shadows, filters, outlines and generated pseudo-elements are unsupported. Every captured alpha sample and the full free margin are checked. Pixel, memory and device limits still apply: a request that does not fit leaves the effect unavailable without trimming or reducing quality. Original content stays usable.

## Shared 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.

## Controls

In the Default appearance, extends frost inward and strengthens mist and particles. With coatingDepth or mistReach, intensity scales strength only; omitted extents are zero.

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` |
| `mistOpacity` Mist opacity; it does not change the ice coating or grains.                                                              | `number` · 0–1 · `1`  |

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.

See [automatic animation and external control](/docs/api/shared/#animation-control) and the [GSAP guide](/docs/gsap/). The [effect instance reference](/docs/api/effect-handle/) documents state, capture updates and cleanup.

## Limits

The effect follows the captured visible shape, including holes and disconnected regions. An opaque image has a rectangular shape. The decorative layer leaves the original content intact.

Only the listed options are public. Every effect except Burned paper permits one main decorative color; gradients, particle counts and whole-element processing are not configurable. Keep the original content usable when output is unavailable. For WebGPU, capture and composition limits, see [browser support](/docs/support/) and [troubleshooting](/docs/troubleshooting/).

## More material effects

* [SlimeA green coating with drips that stretch and fall.`attachSlime`](/docs/api/effects/slime/)
* [Burned paperAn uneven charred rim with brown scorching and sparse glowing seams. Writable emberGlow changes the glow without removing char or scorching.`attachBurnedPaper`](/docs/api/effects/burned-paper/)

Compare every effect side by side in the [gallery](/effects/#frost).
