@generative-forms/react-form

A robust React form engine based on generated JSON configurations and turns them into strictly typed multi-step form experiences.

1. Purpose

This package provides the UI layer for the Generative Forms ecosystem. It consumes a FormConfiguration (generated via AI or manual schema) and renders a fully functional form with:

• Automatic Type Inference: Deeply nested data structures are inferred directly from your config.
• Multi-Step Orchestration: Internal state management for navigation, validation, and data accumulation.
• Context-Aware Validation: Real-time validation powered by TanStack Form.

Example Integrations: See gf-react-integrations for example projects integrating this package with different React frameworks.

2. Requirements

• React: 18.0.0 or higher.

3. Setup

3.1 Style Setup

3.1.1 Project without Tailwind

Import the desired bundled themed CSS file in your application's entry point:

import "@generative-forms/react-form/themes/default.theme.css";

Themes:

You can import a specific theme instead of the default:

import "@generative-forms/react-form/themes/blue.theme.css";
// or
import "@generative-forms/react-form/themes/green.theme.css";
// or
import "@generative-forms/react-form/themes/orange.theme.css";
// or
import "@generative-forms/react-form/themes/red.theme.css";
// or
import "@generative-forms/react-form/themes/violet.theme.css";
// or
import "@generative-forms/react-form/themes/yellow.theme.css";

What's included:

• Complete Tailwind v4 base styles and utilities
• shadcn/ui theme variables (light and dark mode)
• All component styles

3.1.2 Project with Tailwind and Shadcn Theme

The library uses Tailwind utility classes with Tailwind and implemented shadcn theming. To ensure the required styles are bundled in your project, add the library's entry point to your CSS source scanning.

In your main CSS file (e.g., globals.css), include the @source directive pointing to the library's distribution:

@import "tailwindcss";

/* Ensure Tailwind scans the library for required classes */
@source "<path>/<to>/node_modules/@generative-forms/react-form/dist/index.js";

Theming Reference:

• shadcn/ui Themes
• shadcn/ui Theme Customization

3.2 Dark Mode

Dark mode works via the .dark class on a parent element. Add the class to enable dark mode:

<div className="dark">
  <GenerativeForm config={myForm} onSubmit={...} />
</div>

Implementation options:

• Manual toggle: Add/remove .dark class via JavaScript
• System preference: Use prefers-color-scheme media query
• Persistence: Store preference in localStorage

Reference:

• Tailwind CSS Dark Mode
• shadcn/ui Dark Mode

4. Usage

4.1 Define Configuration

To get full IDE autocomplete and type safety, define your configuration using the defineGenerativeFormConfig helper.

Why? This prevents TypeScript from "widening" your step and group keys to generic strings, allowing the engine to know exactly which fields exist at compile time.

import { defineGenerativeFormConfig } from "@generative-forms/react-form";

const registrationForm = defineGenerativeFormConfig({
  id: "user-reg",
  ...
})

4.2 Implementation

The GenerativeForm component handles the rendering and state transitions.

import { GenerativeForm } from "@generative-forms/react-form";

export function MyForm() {
  return (
    <GenerativeForm
      config={registrationForm}
      onStepSuccess={{
        personalStep: (data) => {
          console.log("Step saved:", data.nameGroup.firstName);
        },
      }}
      onSubmit={(allData) => {
        console.log("Form Complete:", allData.personalStep.nameGroup.firstName);
      }}
    />
  );
}