Guides

The React adapter

A reciprocal field as a React component. React is a peer dependency — the one approved framework dep; the core engine stays zero-dependency.

Install

npm i @field-ui/react

<FieldField>

Mounts a fixed, full-viewport canvas behind your app and runs the engine — the same field the web component and mountField() wrap. Bodies are still plain [data-body] elements anywhere in your tree.

React

import { FieldField } from '@field-ui/react';

export function App() {
  return (
    <>
      <FieldField accent="#4da3ff" />
      <a data-body="attract" data-strength="0.9" data-range="320" data-feedback>
        pull me
      </a>
    </>
  );
}

It accepts every FieldOptions prop (accent, density, waves, render, palette, mass, attention, causality) plus className / style.

onReady — get the handle

Because React renders bodies after the field mounts, call field.scan() once your elements are in the DOM. onReady hands you the live FieldHandle:

React

// the field reacts to [data-body] elements anywhere on the page.
// after rendering new bodies, rescan from onReady:
<FieldField
  palette="heatmap"
  attention
  onReady={(field) => field.scan()}
/>

useFieldField — own the canvas

For full control of the canvas element, use the hook form. It returns a canvasRef to attach and a fieldRef holding the handle.

React

import { useFieldField } from '@field-ui/react';

function Background() {
  // own the canvas element yourself
  const { canvasRef, fieldRef } = useFieldField({ accent: '#4da3ff' });
  return <canvas ref={canvasRef} className="my-field" />;
}