React

Tamaño del canvas, opciones completas, props mutables, limpieza en Strict Mode y referencias imperativas.

FlagCloth es un wrapper pequeño alrededor del núcleo independiente de frameworks. Crea un contenedor y una instancia al montarse, aplica las opciones mutables mediante setOptions() y destruye la instancia durante la limpieza.

import { useRef } from 'react';
import {
  FlagCloth,
  type Attachment,
  type FlagClothInstance,
} from 'flag-cloth/react';

const attachment = {
  points: [[0, 0], [0, 8], [0, 16], [0, 24]],
} satisfies Attachment;

export function Banner() {
  const flag = useRef<FlagClothInstance>(null);

  return (
    <FlagCloth
      ref={flag}
      texture="/flag.webp"
      width={3}
      height={2}
      segments={{ x: 40, y: 24 }}
      attachment={attachment}
      canvasWidth="100%"
      canvasHeight={560}
      wind={{ strength: 7, turbulence: 0.35 }}
      interaction={{ enabled: true, dragRadius: 1 }}
      onReady={(instance) => console.log(instance.stats)}
      onError={(error) => console.error(error)}
    />
  );
}

Tamaño del canvas y tamaño de la tela

Son medidas distintas:

Props	Función
`width` y `height`	Dimensiones físicas de la tela en unidades de simulación. Controlan las longitudes de reposo y la proporción.
`canvasWidth` y `canvasHeight`	Dimensiones CSS del contenedor creado por React. Aceptan valores CSS normales como `720`, `'100%'`, `'60vh'` o `'min(100%, 900px)'`.

El canvas llena ese contenedor. ResizeObserver actualiza el viewport CSS y el buffer de la GPU sin recrear la simulación. La resolución interna también queda limitada por renderer.maxPixelRatio.

Puedes usar className o style cuando el diseño pertenezca al CSS:

<FlagCloth
  className="flagViewport"
  style={{ width: '100%', aspectRatio: '3 / 2' }}
  texture="/flag.webp"
/>

.flagViewport {
  width: min(100%, 900px);
  height: clamp(320px, 55vw, 600px);
}

Si proporcionas ambos, canvasWidth y canvasHeight sustituyen las dimensiones correspondientes de style. El contenedor debe resolver a un ancho y alto mayores que cero antes de que el renderizador pueda dibujar.

Props

FlagClothProps contiene todas las propiedades de FlagClothOptions excepto container, que solo pertenece a la API vanilla, además de:

Prop	Tipo	Función
`className`	`string`	Clase del contenedor del canvas.
`style`	`CSSProperties`	CSS en línea del contenedor.
`canvasWidth`	`CSSProperties['width']`	Ancho explícito del contenedor.
`canvasHeight`	`CSSProperties['height']`	Alto explícito del contenedor.
`onReady`	`(instance) => void`	Se ejecuta después de cargar la textura inicial.
`onError`	`(error) => void`	Recibe errores de la textura inicial o de actualizaciones mutables.

La unión completa de sujeciones, incluidos bordes parciales y puntos personalizados, se explica en Sujeciones y puntos fijos. Todos los demás valores predeterminados aparecen en Configuración.

Props mutables

Los cambios de estas props utilizan la instancia existente:

texture, attachment, wind, simulation, interaction, renderer, material, lighting, camera, visibility y debug
width, height y segments reconstruyen la topología manteniendo el canvas y el contexto WebGL2
canvasWidth, canvasHeight, className y style cambian el tamaño mediante el layout normal del navegador y ResizeObserver

advanced y autoStart solo se aplican al construir. Los cuatro atributos del contexto WebGL2 —renderer.alpha, antialias, desynchronized y powerPreference— también son opciones de construcción.

Las posiciones de partículas y el bucle de animación nunca entran en el estado de React, así que la animación no provoca renders de React. Mantener estables los objetos de opciones con useMemo puede evitar llamadas redundantes a setOptions() en componentes padre que se renderizan con frecuencia, pero no es necesario para el funcionamiento correcto.

Referencia imperativa

La ref reenviada es la misma FlagClothInstance que devuelve createFlagCloth():

<button onClick={() => flag.current?.reset()}>Restablecer</button>
<button onClick={() => flag.current?.pause()}>Pausar</button>
<button onClick={() => flag.current?.resume()}>Continuar</button>

Utiliza la ref para eventos imperativos. La configuración normal debe permanecer en las props para que React siga siendo la fuente de verdad.

Strict Mode

El ciclo montar/limpiar/montar de React Strict Mode en desarrollo es seguro. Durante la limpieza, cada instancia elimina su frame de animación, observadores, listeners de Pointer Events, recursos de GPU, panel de depuración opcional y canvas creado por la biblioteca.