` HTML attributes, except for conflicting `onError`, `draggable`, `onTransitionStart`, and `onTransitionEnd` attributes. The component renders a `

` and defaults its inline style to `position: relative; width: 100%; height: 100%`; your `style` can override these values. Its parent still needs a meaningful size. ```tsx import { VaryloomSlider } from 'varyloom/react'; const items = [ { image: '/images/first.jpg', alt: 'First image' }, { image: '/images/second.jpg', alt: 'Second image' }, ]; function Gallery() { return (

console.log(controller.effect)} onIndexChange={({ index }) => console.log(index)} />

); } ``` Keep the `items` array in a stable variable or memoize it to avoid recreating the controller on each render. | Callback / ref | Argument | | --- | --- | | `onReady` | `VaryloomController` after `createVaryloom` resolves. | | `onIndexChange` | `indexchange` payload. | | `onTransitionStart` | `transitionstart` payload. | | `onTransitionEnd` | `transitionend` payload. | | `onEffectChange` | `effectchange` payload. | | `onFallback` | `fallback` payload. | | `onError` | An `Error`, unwrapped from a controller `error` event or initial creation rejection. | | `ref` | Controller after readiness; reset to `null` on cleanup. | There is no `onProgress` prop; use `controller.on('progress', ...)` after `onReady` or via the ref. The component subscribes to controller events **after** `createVaryloom` resolves, so its `onEffectChange` and `onFallback` callbacks do not receive events from the initial mount. `onReady` and the ref expose the active effect and index. Changing the `items` array reference, `registry`, or `startIndex` destroys and recreates the controller. Other Varyloom option prop changes call `setOptions` on the existing controller. Keep `items` stable across renders unless recreation is intended. The component destroys the controller on unmount; changes to callback props alone use the latest callback without recreation. ## Registry and custom effects `TransitionRegistry` has `register(definition)`, `replace(definition)`, `get(name)`, `has(name)`, `unregister(name)`, `list()`, and `clone()`. `register` throws on a duplicate or empty name; `replace` overwrites an existing name. `clone` copies the definitions into a new registry, not the effect instances. `defineTransition(definition)` returns the same definition for typing. `registerTransition(definition)` replaces the definition in the global registry and returns an unregister function; that function removes the name only while the registered object is still current. It does not restore a previous definition. To scope effects to one slider, pass a `TransitionRegistry` as `options.registry`. A custom registry must include the selected `effect` and any configured `fallbackEffect`. `builtInTransitions` is the ordered array of the 31 built-in definitions; you can register them in a scoped registry. The `TransitionRegistryLike` option contract itself requires only `get(name)` and `list()`. ```ts import { TransitionRegistry, builtInTransitions, defineTransition, } from 'varyloom'; const registry = new TransitionRegistry(); builtInTransitions.forEach((definition) => registry.register(definition)); registry.register(defineTransition({ name: 'my-transition', backend: 'custom', defaults: { color: '#fff' }, create: () => { const canvas = document.createElement('canvas'); return { canvas, init({ host }) { host.appendChild(canvas); }, prepare(fromIndex, toIndex, direction) {}, resize(width, height, dpr) {}, render(frame) {}, destroy() { canvas.remove(); }, }; }, })); ``` `TransitionDefinition` requires `name: TransitionName`, `backend: 'webgl2' | 'webgpu' | 'ogl' | 'custom'`, and `create(): TransitionEffect`. The backend field is descriptive metadata; the controller uses `supported()` to decide compatibility, not `backend`. Optional `defaults` are shallow-merged with requested `effectOptions`. Optional `supported(): boolean | Promise` is called before mounting. Optional `phaseEasing` overrides the controller's easing for the progress tween; use `'none'` for linear simulation time. `TransitionEffect` must expose `canvas: HTMLCanvasElement` and these methods: | Method / property | Contract | | --- | --- | | `init(context): void \| Promise` | Initialize with the host, all loaded items, width, height, DPR, merged options, and `reportError(error)`. Append whatever DOM the effect needs to `context.host`. | | `prepare(fromIndex, toIndex, direction): void \| Promise` | Prepare a source/target pair. Called on initial mount with the same index twice, then before transitions and after completion/cancellation. | | `resize(width, height, dpr): void` | Respond to initial mount and container resize. | | `render(frame): void \| Promise` | Draw the current frame. Rejected render Promises emit `error`; synchronous throws are not caught by the render loop. | | `destroy(): void` | Release effect-owned DOM and GPU resources when replaced or destroyed. | | `continuous?: boolean` | If true, request rendering every animation frame even while idle; otherwise render when dirty or transitioning. | `LoadedImage` adds `source: HTMLImageElement | ImageBitmap`, `width`, `height`, and `release()` to the original `VaryloomItem`. These loaded objects are given to the effect during `init` and belong to the controller; custom effects should not release them. `TransitionFrame` contains `progress` (normally moving from `0` to `1`; a custom GSAP ease can overshoot), `time` (seconds since initialization), `delta` (seconds between rendered frames, clamped by the controller), `duration`, `direction` (`-1` or `1`), `active`, `pointer: { x, y }`, and merged `options`. The pointer starts at `{ x: 0.5, y: 0.5 }` and updates on pointer down; its `y` coordinate increases upward. `active` is true while a transition is animating. Custom effects can report recoverable errors with `context.reportError(error)`. Fallback is attempted only when the requested definition exists and its `supported()` returns false. An unknown effect, failed `supported()` call, failed `create`/`init`/`prepare`, or failed graphics initialization is not automatically replaced by the fallback. If no usable fallback is configured, effect mounting fails. A built-in capability test may only check whether an API is exposed, so confirm actual context/device creation on target browsers. ## Built-in names and backends Each name below is a `BuiltInTransitionName`; the matching TypeScript option interface is exported from `varyloom` (for example, `InkRevealOptions` and `ParticleShiftOptions`). Each definition is also exported as a camel-case `*Transition` constant. | Backend | Effect names | | --- | --- | | WebGPU | `particle-shift`, `chromatic-dust`, `fiber-flow`, `meteor-wake` | | OGL / WebGL | `melt` | | Custom DOM/canvas | `drowsy-blinds`, `postcard-relay`, `type-aperture`, `archive-seal`, `contact-sheet`, `memory-mosaic`, `iris-shutter` | | WebGL2 | `ink-reveal`, `prismatic-glass`, `silk-ribbons`, `misregistration`, `burn-through`, `rack-focus`, `liquid-lens`, `torn-paper`, `frequency-handoff`, `flow-morph`, `darkroom-develop`, `impasto-stroke`, `lenticular-shift`, `holo-foil`, `contour-reveal`, `depth-flip`, `gummy-squeeze`, `zipper-cloth`, `vortex-portal` | WebGPU definitions currently check for `navigator.gpu`; WebGL2 definitions check for `WebGL2RenderingContext`; `melt` checks for `WebGLRenderingContext`. These checks do not guarantee that a device, context, shader, or texture can be created successfully.