@squaredr/fieldcraft-react

React renderer for @squaredr/fieldcraft-core — 44 pre-built form fields, hooks, theming, and a pluggable field registry. Styled with Tailwind CSS via shadcn/ui primitives.

Install

npm install @squaredr/fieldcraft-core @squaredr/fieldcraft-react

Quick Start

import { FormEngineRenderer } from "@squaredr/fieldcraft-react";
import "@squaredr/fieldcraft-react/styles.css";
import type { FormEngineSchema, FormResponse } from "@squaredr/fieldcraft-core";

const schema: FormEngineSchema = {
  id: "feedback",
  version: "1.0.0",
  title: "Feedback",
  submitAction: { type: "callback" },
  sections: [
    {
      id: "main",
      title: "Your Feedback",
      questions: [
        { id: "name", type: "short_text", label: "Name", required: true },
        { id: "rating", type: "rating", label: "How would you rate us?", config: { maxStars: 5 } },
        { id: "comments", type: "long_text", label: "Comments" },
      ],
    },
  ],
};

function App() {
  const handleSubmit = async (response: FormResponse) => {
    console.log(response);
  };

  return <FormEngineRenderer schema={schema} onSubmit={handleSubmit} />;
}

That's it. FormEngineRenderer creates its own engine, renders all fields, handles validation, and calls your onSubmit callback.

Styling

Import the pre-built stylesheet in your app entry point:

import "@squaredr/fieldcraft-react/styles.css";

Or if you use Tailwind CSS v4, import the stylesheet and let Tailwind scan the distributed component classes:

@import "@squaredr/fieldcraft-react/styles.css";

CSS Architecture

All field components use semantic .fc-* CSS classes (FieldCraft namespace) defined in the stylesheet. Visual styling flows through CSS custom properties set by FormEngineThemeProvider, so you can override any aspect with your own CSS:

/* Override in your own stylesheet */
.fc-option-active {
  border-color: var(--primary);
  background: var(--primary / 0.08);
}

Components

Core

| Component | Description | |-----------|-------------| | FormEngineRenderer | Full form renderer — pass a schema and get a working form | | SectionRenderer | Renders a single section of fields | | FieldRenderer | Renders a single field by type | | ProgressBar | Multi-section progress indicator | | NavigationButtons | Back/Next/Submit buttons | | ErrorSummary | Validation error list | | CompletionScreen | Post-submit confirmation |

Field Types (44)

Text: ShortTextField, LongTextField, EmailField, PhoneField, PhoneInternationalField, UrlField, LegalNameField

Numeric: NumberField, SliderField, RatingField, NpsField, LikertField, OpinionScaleField

Selection: SingleSelectField, MultiSelectField, DropdownField, BooleanField, CountrySelectField, RankingField

Date/Time: DateField, DateRangeField, TimeField, AppointmentField

Media: FileUploadField, SignatureField, ImageCaptureField

Advanced: AddressField, PaymentField, MatrixField, RepeaterField, CalculatedField, HiddenField, ScoringField

Structural: ConsentField, InfoBlockField

UI Primitives (shadcn/ui)

Re-exported for use in custom field components and pro packages:

Alert, Badge, Button, Calendar, Card, Checkbox, Collapsible, Input, Label, Popover, Progress, RadioGroup, Select, Separator, Slider, Switch, Table, Textarea, Toggle, ToggleGroup

Engine & Hooks

The react package re-exports createEngine, FormEngine, EngineOptions, and ValidationResult from @squaredr/fieldcraft-core for convenience — no need to import from core separately:

import { useFormEngine, createEngine } from "@squaredr/fieldcraft-react";
import type { FormEngine } from "@squaredr/fieldcraft-react";

useFormEngine

import { useFormEngine } from "@squaredr/fieldcraft-react";

function CustomForm({ schema }) {
  const engine = useFormEngine(schema);

  return (
    <div>
      <p>Current section: {engine.state.currentSectionId}</p>
      <button onClick={() => engine.setValue("name", "Alice")}>Set name</button>
      <button onClick={() => engine.nextSection()}>Next</button>
    </div>
  );
}

The hook returns a proxy that is resilient to React Strict Mode — it lazily re-creates the engine if it was destroyed during a Strict Mode remount cycle.

| Hook | Description | |------|-------------| | useFormEngine(schema, options?) | Creates and subscribes to a form engine | | useFieldValue(engine, questionId) | Reactive field value | | useFieldError(engine, questionId) | Reactive field error | | useSectionProgress(engine) | Section completion progress |

Theme Presets

import { FormEngineRenderer, darkPreset } from "@squaredr/fieldcraft-react";

<FormEngineRenderer schema={schema} onSubmit={handleSubmit} theme={darkPreset} />

Available presets: cleanPreset, modernPreset, darkPreset, highContrastPreset, clinicalPreset, playfulPreset

Custom Field Registry

Override or add field components:

import { createFieldRegistry, mergeRegistries, defaultRegistry } from "@squaredr/fieldcraft-react";

const customRegistry = mergeRegistries(defaultRegistry, {
  short_text: MyCustomTextField,
});

<FormEngineRenderer schema={schema} onSubmit={handleSubmit} components={customRegistry} />

Peer Dependencies

• react ^18 || ^19
• react-dom ^18 || ^19
• @squaredr/fieldcraft-core ^1.3.2

Community

• Discord — Get help, share projects, request features
• Docs — Full documentation
• GitHub — Source code and issues
• Pro Tools — Visual FormBuilder, SchemaEditor, ResponseViewer, ThemeEditor

License

MIT