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​

Choose the package for your framework:

# React
npm install @formitiva/react

# Vue
npm install @formitiva/vue

# Angular
npm install @formitiva/angular

# Vanilla JS / TypeScript
npm install @formitiva/vanilla

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.

The form definition is the same across all frameworks:

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' }
  ]
};

React​

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

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

Vue​

<script setup lang="ts">
import { Formitiva } from '@formitiva/vue';
</script>

<template>
  <Formitiva :definition-data="definition" />
</template>

Angular​

import { Component } from '@angular/core';
import { FormitivaComponent } from '@formitiva/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FormitivaComponent],
  template: `<fv-formitiva [definitionData]="definition"></fv-formitiva>`,
})
export class AppComponent {
  definition = definition;
}

Vanilla JS​

import { Formitiva } from '@formitiva/vanilla';

const form = new Formitiva({ definitionData: definition });
await form.mount(document.getElementById('app')!);

Handle submission​

In the above examples, users can see the forms and edit inputs. The next step is getting the input values and submitting them.

Formitiva provides 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 the following examples, the first approach is used. For the second approach, please check Submission

The submission handler signature is the same across all frameworks:

import type { FormSubmissionHandler } from '@formitiva/react'; // or /vue, /angular, /vanilla

const alertSubmission: FormSubmissionHandler = (
  definition, instanceName, valuesMap, t
): string[] | undefined => {
  const instance = {
    name: instanceName || 'Unnamed Instance',
    version: (definition as any)?.version || '',
    definition: (definition as any)?.name || '',
    values: valuesMap,
  };
  alert(JSON.stringify(instance, null, 2));
  return undefined;
};

React​

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

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

Vue​

<script setup lang="ts">
import { Formitiva } from '@formitiva/vue';
</script>

<template>
  <Formitiva :definition-data="definition" :on-submit="alertSubmission" />
</template>

Angular​

import { Component } from '@angular/core';
import { FormitivaComponent } from '@formitiva/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FormitivaComponent],
  template: `<fv-formitiva [definitionData]="definition" [onSubmit]="alertSubmission"></fv-formitiva>`,
})
export class AppComponent {
  definition = definition;
  alertSubmission = alertSubmission;
}

Vanilla JS​

import { Formitiva } from '@formitiva/vanilla';

const form = new Formitiva({
  definitionData: definition,
  onSubmit: alertSubmission,
});
await form.mount(document.getElementById('app')!);

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​