Forge Form

Features

• Lightweight — Under 4KB gzipped
• Type-safe — Full TypeScript support
• Built-in Validators — 15+ validators, no external dependencies
• DevTools — Inspect fields, validation, and logs in real-time
• Framework Support — React (Vue & Angular coming soon)
• Zero Config — Works out of the box

Installation

npm install @forgedevstack/forge-form

Quick Start

1. Wrap your form with FormProvider

import { FormProvider } from '@forgedevstack/forge-form';

function App() {
  return (
    <FormProvider
      initialValues={{ email: '', password: '' }}
      onSubmit={(values) => console.log(values)}
    >
      <LoginForm />
    </FormProvider>
  );
}

2. Use fields with useField

import { useField, useForm, Validators } from '@forgedevstack/forge-form';

function LoginForm() {
  const { handleSubmit } = useForm();
  
  const email = useField('email', {
    validators: [Validators.required(), Validators.email()],
  });
  
  const password = useField('password', {
    validators: [Validators.required(), Validators.minLength(8)],
  });

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <input {...email.inputProps} placeholder="Email" />
        {email.field.touched && !email.field.valid && (
          <span>{email.field.errors[0]?.message}</span>
        )}
      </div>
      
      <div>
        <input {...password.inputProps} type="password" placeholder="Password" />
        {password.field.touched && !password.field.valid && (
          <span>{password.field.errors[0]?.message}</span>
        )}
      </div>
      
      <button type="submit">Login</button>
    </form>
  );
}

3. Add DevTools (optional)

import { ForgeFormDevTools } from '@forgedevstack/forge-form/devtools';

function App() {
  return (
    <FormProvider {...config}>
      <MyForm />
      <ForgeFormDevTools />
    </FormProvider>
  );
}

Validators

All validators are built-in — no external dependencies:

import { Validators } from '@forgedevstack/forge-form';

// Basic
Validators.required('Custom message')
Validators.email()
Validators.url()
Validators.phone()

// Numbers
Validators.number()
Validators.integer()
Validators.positive()
Validators.min(5)
Validators.max(100)

// Strings
Validators.minLength(3)
Validators.maxLength(50)
Validators.pattern(/^[A-Z]/)

// Advanced
Validators.match('confirmPassword')
Validators.oneOf(['admin', 'user'])
Validators.custom((value) => value !== 'forbidden')
Validators.compose(Validators.required(), Validators.email())
Validators.when((value) => value.length > 0, Validators.email())

API Reference

FormProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | initialValues | object | {} | Initial form values | | validateOnChange | boolean | true | Validate on input change | | validateOnBlur | boolean | true | Validate on field blur | | validateOnSubmit | boolean | true | Validate before submit | | onSubmit | function | - | Submit handler | | onError | function | - | Error handler | | onReset | function | - | Reset handler |

useForm Return

const { form, handleSubmit, handleReset } = useForm();

// form contains:
form.values        // Current values
form.errors        // Validation errors
form.valid         // Is form valid
form.dirty         // Has any field changed
form.touched       // Has any field been touched
form.submitting    // Is submitting
form.submitted     // Was submitted
form.submitCount   // Number of submit attempts

useField Return

const { field, actions, inputProps } = useField('email', options);

// field contains:
field.value        // Current value
field.valid        // Is valid
field.errors       // Validation errors
field.touched      // Has been touched
field.dirty        // Has changed
field.validating   // Is validating

// actions:
actions.setValue(value)
actions.setTouched(true)
actions.setError({ valid: false, message: 'Error' })
actions.clearErrors()
actions.validate()
actions.reset()

// inputProps for native inputs:
<input {...inputProps} />

DevTools

The DevTools panel shows:

• Fields tab — All fields with their state (valid, touched, dirty)
• Logs tab — Real-time activity log (register, change, validate, submit)
• Form stats — Total fields, validity, submit count

<ForgeFormDevTools
  enabled={true}
  position="bottom-right"
  maxLogs={100}
/>

TypeScript

Full type inference:

interface LoginForm {
  email: string;
  password: string;
}

const { form } = useForm<LoginForm>();
form.values.email // typed as string

Part of ForgeStack

Forge Form is part of the ForgeStack ecosystem:

• Harbor — Node.js backend framework
• Synapse — State management
• Bear — UI components
• Forge Query — Data fetching
• Forge Form — Form management

License

MIT © ForgeDevStack