Guides

The TypeScript wrapper

@field-ui/vanilla is the framework-free door — a typed FieldField class for plain TypeScript apps, with no custom element to register and no framework dependency. It wraps the same zero-dependency engine the web component and React adapter do.

Install

npm i @field-ui/vanilla

The FieldField class

new FieldField() builds a fixed, full-viewport canvas behind your page and starts the engine on it. It takes every FieldOptions value, implements the full FieldHandle surface, and exposes the canvas it runs on. Importing the package has no side effects — it never registers a custom element.

TypeScript

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

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

field.setFormation('wells');
field.burst(window.innerWidth / 2, 200);

// …later
field.destroy();   // stops the loop AND removes the managed canvas

Drive a canvas you own

Pass your own <canvas> and the field never creates or removes one — destroy() only stops the engine. Use this when you place and size the canvas yourself.

TypeScript

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

// drive a <canvas> you place and size yourself — nothing is created or removed,
// and destroy() only stops the engine.
const field = new FieldField({ canvas: myCanvas, density: 1.2 });

mountField — the factory form

Prefer a plain function over a class? mountField() returns the bare FieldHandle; its destroy() also removes the canvas it made. createField() is re-exported too, for when you own the canvas and want the lowest-level entry — see the core engine guide.

TypeScript

import { mountField, createField } from '@field-ui/vanilla';

// the plain factory form — same managed canvas, returns the bare FieldHandle
const field = mountField({ render: 'trails' });

// or own the canvas entirely with the lowest-level entry:
const own = createField(document.querySelector('canvas'), { accent: '#2dd4bf' });

One package, everything vanilla. The catalog data (FORCES, FORMATIONS, CONDITIONS, PALETTE) and the engine contracts are re-exported, so a force picker or legend needs no second install.