Skip to content

Scanlines

Fine horizontal bands move along the edge.

Live preview needs JavaScript and WebGPU.

Category
Pattern
Function
attachScanlines
Options
PatternOptions
Package
@domfx/browser

Usage

attachScanlines(target: Element, options: PatternOptions): ColorEffectHandle

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 includes the required HTML and CSS.

import { attachScanlines } from '@domfx/browser';
import type { PatternOptions } from '@domfx/browser';

// Run after mount; host contains target and has position: relative.
const options: PatternOptions = {
  host, clock: 'auto', intensity: 0.8,
  plumeReach: 0.1,
  bandDepth: 0.05,
};
const effect = attachScanlines(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

Set these options when creating the instance. Values are finite nonnegative numeric fractions of the untransformed target border box, excluding capture padding. Transparent image margins count; tight visible-pixel bounds are not used. Fractions resolve again when the target resizes. Changing an option requires a new instance.

PropertyType and unitExample
plumeReach

Plume reach

number · fraction of local physical height0.1 = 10%
bandDepth

Inward band depth

number · fraction of the shorter local side0.05 = 5%

Omitting every extent option keeps the Default appearance, including its relationship to intensity. Supplying an option enables relative mode: intensity scales premultiplied output without changing emitters, the grid, marks or spacing. Output is transparent when every extent is zero.

plumeReach sets upward emitter travel; bandDepth sets inward coverage. In relative mode, a missing partner is zero and disables that component. For example, plumeReach: 0.1 means 10 CSS pixels on a 100px-high target and 40 on a 400px-high target. Marks retain their local scale: Dither keeps its fine dots and 2px grid.

Reach is a permitted envelope, not a guaranteed visible tip. Marks sampled near its edge may extend beyond it; allocation reserves 6 CSS pixels for all mark footprints, plus the sampling guard. Opacity can change thresholded visible bounds.

Relative mode requires contained descendants, no shadows, filters, CSS outlines or generated pseudo-elements, and paint within the target border box plus 2 CSS pixels. Actual paint and the full free margin are checked. DPR changes resolution and admission, not the CSS fraction. Capture and memory limits still apply: requests that do not fit make the effect unavailable, without trimming reach 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.

PropertyTypeDefault
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.

HTMLElementRequired
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.

number0
time

Initial effect time in seconds. Negative values are accepted.

number0
intensity

Initial effect strength. Accepted values clamp to 0–1; the visual response depends on the effect.

number1
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 | undefinedOmitted (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

With extent options omitted: Strengthens the pattern and extends its reach. In relative mode, intensity scales opacity without changing extent or marks.

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.

PropertyType
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.

See automatic animation and external control and the GSAP guide. The effect instance reference 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 and troubleshooting.

Compare every effect side by side in the gallery.