Configuration

Every constructor option, its exact default, and whether it can change at runtime.

createFlagCloth() accepts a FlagClothOptions object. The React component accepts the same options except container, because it creates that element for you. Nested groups are partial: pass only the values you want to change.

import type { FlagClothOptions } from 'flag-cloth';

Required values

Option	Type	Default	Meaning
`container`	`HTMLElement`	required	Element that hosts and sizes the canvas. Vanilla API only.
`texture`	`string \| TexImageSource \| null`	required	Image URL, ready browser image source, or `null` to render `material.baseColor`.

Cloth topology and lifecycle

Option	Type	Default	Meaning
`width`	`number`	`3`	Cloth width in simulation units, not CSS pixels.
`height`	`number`	`2`	Cloth height in simulation units, not CSS pixels.
`segments.x`	`number`	`32`	Horizontal cell count. There are `x + 1` particle columns.
`segments.y`	`number`	`20`	Vertical cell count. There are `y + 1` particle rows.
`attachment`	`Attachment`	`'left'`	Edge, corner, partial edge, custom grid points, or `'none'`.
`autoStart`	`boolean`	`true`	Marks the instance as started immediately and schedules its owned animation loop.

Changing width, height, or segments rebuilds the simulation topology but keeps the same canvas, WebGL2 context, renderer instance, observers, and event controllers. Changing attachment only rebuilds the pin mask. See Attachments for every accepted shape.

Wind

Property	Type	Default	Meaning
`direction`	`[number, number, number]`	`[1, 0.08, 0.3]`	World-space direction, normalized internally. A zero vector disables directional wind.
`strength`	`number`	`7`	Base wind speed.
`turbulence`	`number`	`0.35`	Strength of noisy gust and lateral variation.
`gustFrequency`	`number`	`0.5`	Rate of time variation in the wind field.
`spatialScale`	`number`	`0.8`	Frequency of spatial variation across the cloth.
`aerodynamicCoefficient`	`number`	`0.35`	Multiplier that converts triangle pressure into particle force.

Simulation

Property	Type	Default	Meaning
`damping`	`number`	`0.985`	Velocity retained over a 1/60-second interval.
`gravity`	`[number, number, number]`	`[0, 0, 0]`	World-space acceleration. Gravity is disabled by default for a conventional flag.
`fixedTimeStep`	`number`	`1 / 60`	Stable accumulator step in seconds.
`maxFrameDelta`	`number`	`0.1`	Maximum display-frame gap accepted by the accumulator, in seconds.
`substeps`	`number`	`2`	Integration subdivisions per fixed step. Values are floored and clamped to at least 1.
`constraintIterations`	`number`	`6`	Structural, shear, and bend solve passes per substep.
`structuralStiffness`	`number`	`1`	Horizontal and vertical distance retention.
`shearStiffness`	`number`	`0.9`	Diagonal distance retention.
`bendStiffness`	`number`	`0.4`	Two-cell distance retention.
`maxCorrection`	`number`	`0.25`	Per-constraint correction cap. Set `0` to disable the cap.
`mass`	`number`	`1`	Total cloth mass, independent of grid density.

Stiffness values are clamped from 0 to 1 by the solver and converted to an iteration-independent correction. See Cloth simulation before raising grid resolution or solver work.

Pointer interaction

Property	Type	Default	Meaning
`enabled`	`boolean`	`true`	Enables mouse, pen, and touch dragging through Pointer Events.
`touchAction`	`'pan-y' \| 'pan-x' \| 'none' \| 'auto'`	`'pan-y'`	Browser touch policy. The default preserves vertical page scrolling and horizontal cloth dragging.
`dragRadius`	`number`	`1`	Grid-space radius around the selected particle.
`dragStiffness`	`number`	`0.9`	Strength of the temporary positional constraint.
`maxDragDistance`	`number`	`4`	Maximum movement from the initial grab point. Set `0` for unlimited movement.
`allowPinned`	`boolean`	`false`	Allows attached particles to be selected temporarily.
`releaseImpulse`	`[number, number, number]`	`[0, 0, 0]`	World-space velocity impulse applied on release.

Renderer

The table shows the default quality profile. Selecting performance changes maxPixelRatio to 1, shadows to false, and shadingUpdateInterval to 2. Explicit values passed alongside a preset win.

Property	Type	Default	Meaning
`preset`	`'quality' \| 'performance'`	`'quality'`	Selects a tested rendering profile.
`alpha`	`boolean`	`true`	Requests an alpha-enabled WebGL2 context. Construction-time only.
`antialias`	`boolean`	`true`	Requests browser multisample antialiasing. Construction-time only.
`desynchronized`	`boolean`	`false`	Requests a desynchronized context when supported. Construction-time only.
`powerPreference`	`WebGLPowerPreference`	`'high-performance'`	GPU preference used during context creation. Construction-time only.
`maxPixelRatio`	`number`	`1.5`	Caps backing-store resolution; values below `0.5` are clamped.
`textureFiltering`	`'linear' \| 'nearest'`	`'linear'`	Image texture sampling mode.
`transparent`	`boolean`	`true`	Clears with alpha instead of `backgroundColor`.
`backgroundColor`	`string`	`'transparent'`	CSS color used when `transparent` is false.
`shadows`	`boolean`	`true`	Enables the nine-sample soft silhouette shadow.
`shadingUpdateInterval`	`number`	`1`	Recalculates normals every N rendered frames.

alpha, antialias, desynchronized, and powerPreference are intentionally absent from FlagClothUpdateOptions.renderer; changing a WebGL context attribute requires creating a new instance.

Material

Property	Type	Default	Meaning
`baseColor`	`string`	`'#f2f4f3'`	Cloth color used when `texture` is null.
`ambient`	`number`	`0.58`	Minimum material brightness.
`diffuse`	`number`	`0.55`	Directional fold-lighting strength.
`specular`	`number`	`0.16`	Highlight strength in the quality preset.
`shininess`	`number`	`18`	Highlight concentration.
`foldContrast`	`number`	`0.42`	Dark/light fold contrast.
`shadowColor`	`string`	`'rgba(0, 0, 0, 0.3)'`	CSS color for the silhouette shadow.
`shadowBlur`	`number`	`18`	Shadow sampling radius in CSS pixels.
`shadowOffsetX`	`number`	`10`	Horizontal shadow offset in CSS pixels.
`shadowOffsetY`	`number`	`12`	Vertical shadow offset in CSS pixels.

Lighting

Property	Type	Default	Meaning
`enabled`	`boolean`	`true`	Enables fold lighting.
`intensity`	`number`	`1`	Overall directional-light multiplier.
`direction`	`[number, number, number]`	`[-0.4, 0.7, 1]`	World-space light direction, normalized internally.

Camera

Property	Type	Default	Meaning
`fov`	`number`	`40`	Vertical perspective field of view in degrees.
`near`	`number`	`0.01`	Near clipping distance.
`far`	`number`	`100`	Far clipping distance.
`position`	`[number, number, number] \| null`	`null`	Camera position. `null` automatically fits the cloth.
`lookAt`	`[number, number, number]`	`[0, 0, 0]`	World-space camera target.

Visibility and debug

Property	Type	Default	Meaning
`visibility.pauseWhenOffscreen`	`boolean`	`true`	Pauses through `IntersectionObserver` while the container is outside the viewport.
`visibility.pauseWhenDocumentHidden`	`boolean`	`true`	Pauses while `document.visibilityState` is hidden.
`debug`	`boolean \| Partial<DebugOptions>`	`false`	Enables or configures the optional overlay.
`debug.enabled`	`boolean`	`false`	Creates the debug overlay.
`debug.updateInterval`	`number`	`500`	Overlay refresh interval in milliseconds, clamped to at least 100.

debug: { updateInterval: 250 } does not enable the panel by itself; include enabled: true or use debug: true.

Advanced integration

Property	Type	Default	Meaning
`canvas`	`HTMLCanvasElement`	library-created	Supplies a caller-owned canvas.
`context`	`WebGL2RenderingContext`	library-created	Supplies a caller-owned context; its canvas is used when `canvas` is omitted.
`externalAnimationLoop`	`boolean`	`false`	Disables internal `requestAnimationFrame` scheduling.

advanced and autoStart are construction-time options and are not part of FlagClothUpdateOptions.

Runtime updates

await flag.setOptions({
  attachment: { points: [[0, 0], [0, 10], [4, 4]] },
  wind: { strength: 11 },
  interaction: { enabled: false },
  renderer: { preset: 'performance' },
});

setOptions() is asynchronous because it can load a new texture. Wind, pinning, simulation, interaction, renderer, material, lighting, camera, visibility, and debug changes do not recreate the WebGL2 context.

Configuration

On this page