Skip to main content

Getting Started

Welcome to Formitiva! This guide gets you productive in under 5 minutes by walking through installation, the smallest “render a form” example, and how to handle submission.

You’ll quickly learn how to:

  • Install the library
  • Define forms as JSON
  • Render a form at runtime (no JSX per field)
  • Handle submissions via onSubmit or a registered handler

By the end, you’ll have a working form rendering from a JSON definition.

Installation​

npm install @formitiva/react
# or
yarn add @formitiva/react
# or
pnpm add @formitiva/react

Quick Start​

Render a form from a JSON definition​

  1. Define your form as JSON.
  2. (Optional) Provide an instance (values) if you want to load/edit existing data.
  3. Render it with Formitiva.
import * as React from 'react';
import { Formitiva } from '@formitiva/react';

// Define a form definition (or fetch it from your API)
const definition = {
  name: 'contactForm',
  version: '1.0.0',
  displayName: 'Contact Form',
  properties: [
    { name: 'name', type: 'text', displayName: 'Name', required: true },
    { name: 'email', type: 'email', displayName: 'Email', required: true },
    { name: 'message', type: 'multiline', displayName: 'Message', minHeight: '80px' }
  ]
};

export function App() {
  // If you don't pass an instance/value object, Formitiva will initialize one from the definition
  return <Formitiva definitionData={definition} />;
}

Handle submission​

In above example, users can see the forms and edit inputs. Next interest step is how to get the input values and submit to specific places.

Formitiva provieds two approaches for value submission:

  1. Pass an onSubmit form submission function directly to Formitiva (simplest).
  2. Use the submission registration system so each definition can reference a handler by name.

In follwing example, the first approach is used. For second approach, please check Submission

import * as React from 'react';
import { Formitiva } from '@formitiva/react';
import type { FormSubmissionHandler } from '@formitiva/react';

const definition = {
  name: 'contactForm',
  version: '1.0.0',
  displayName: 'Contact Form',
  properties: [
    { name: 'name', type: 'text', displayName: 'Name', required: true },
    { name: 'email', type: 'email', displayName: 'Email', required: true },
    { name: 'message', type: 'multiline', displayName: 'Message', minHeight: '80px' },
  ],
};

const alertSubmission: FormSubmissionHandler = (
  definition, instanceName, valuesMap, t
): string[] | undefined => {
  void t; // unused in this demo
  const instance = {
    name: instanceName || "Unnamed Instance",
    version: (definition as any)?.version || "",
    definition: (definition as any)?.name || "",
    values: valuesMap as Record<string, FieldValueType | unknown>,
  };
  const instanceStr = JSON.stringify(instance, null, 2);
  alert(instanceStr);
  return undefined;
};

export function App() {
  return (
    <Formitiva
      definitionData={definition}
      onSubmit={alertSubmission}
    />
  );
}

Core Concepts​

  • Definition: the JSON schema describing fields, labels, defaults, and behavior.
  • Instance: existing values for editing (optional).
  • Field: a rendered input (text, select, date, etc.) described by the definition.
  • Validation: built-in rules plus custom validators.
  • Submission: send the current values map to your handler (onSubmit or a registered handler).

Next Steps​