Getting started

Build with field-ui.

A reciprocal DOM-physics field for the web — framework-agnostic, zero runtime dependencies. Get a field reacting to your elements in under a minute.

Install

Pick the entry point that matches your stack. The core engine has zero runtime dependencies; the adapters wrap it.

npm i @field-ui/elements the <field-root> web component — drops into any framework or plain HTML

npm i @field-ui/react the <FieldField> React component + useFieldField hook

npm i @field-ui/vanilla the framework-free FieldField class + mountField() for plain TypeScript

npm i field-ui the engine itself — when you own the canvas

Quick start

The same field, three ways — pick the tab that matches your stack. Each snippet is the whole setup: register the field, then mark an element as a body. Hit Copy and paste.

<!-- 1. register the element -->
<script type="module">
  import '@field-ui/elements';
</script>

<!-- 2. drop the field + mark any element as a body -->
<field-root accent="#4da3ff"></field-root>

<a data-body="attract" data-strength="0.9" data-range="320" data-feedback>
  pull me
</a>

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

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

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

// builds + manages a fixed full-viewport canvas, starts the engine
const field = new FieldField({ accent: '#4da3ff' });

// any [data-body] element on the page becomes a force the field reacts to.
// after adding bodies to the DOM, rescan:
field.scan();

The field reacts to the page. A single full-viewport canvas runs behind your content and reads every [data-body] element each frame — so any layout change is a change to the force geometry. After you add or remove bodies, call field.scan().

The mental model

Bodies. Any element with data-body="<force> <force>…" becomes a force (forces compose). Tune it with data-strength, data-range, data-color, and a condition gate data-when.
The field. One conserved pool of particles. Nothing is created from nothing; matter is moved, captured, and released — never faked.
Reciprocity. Add data-feedback and the field writes the local density it gathered back into your element as the --d custom property — drive weight, glow, and scale from it.

Where to go next

Concepts The model in depth — bodies, the single field, reciprocity, conservation. The 34 forces The full API reference — law, attributes, and an example per force. Framework guides Web component, TypeScript, React, and the core engine — pick your entry point. The Lab A physics detector — fire a particle into any force and verify its behavior. Design system The visual language behind the field — tokens, the force palette, type, and glyphs.