FormGuardian React

Build production-ready React forms in minutes with built-in validation, TypeScript support, and beautiful defaults.

npm install formguardian-react

Why FormGuardian?

• ⚡ Fast Setup - Working form in 5 minutes
• 🎯 Smart Validation - 10+ built-in validators + custom logic
• 🎨 Zero Config Styling - Beautiful out of the box
• 🔒 Type-Safe - Full TypeScript support

Quick Example

import { DynamicForm, FieldConfig } from 'formguardian-react';
import 'formguardian-react/styles';

const fields: FieldConfig[] = [
  {
    name: "email",
    type: "email",
    label: "Email",
    required: true,
    validators: [
      { type: "email", message: "Invalid email" }
    ]
  },
  {
    name: "password",
    type: "password",
    label: "Password",
    validators: [
      { type: "minLength", value: 8, message: "Min 8 characters" }
    ]
  }
];

function App() {
  return (
    <DynamicForm
      fields={fields}
      onSubmit={(values) => console.log(values)}
      submitButtonText="Sign In"
    />
  );
}

Core Concepts

Field Configuration

Each field needs a name (required) and accepts these common options:

{
  name: "email",              // Required - unique identifier
  type: "email",              // Input type (default: "text")
  label: "Email Address",     // Display label
  required: true,             // Mark as required
  validators: [],             // Validation rules
  placeholder: "[email protected]"
}

Validation

Add multiple validators per field - they run in order:

validators: [
  { type: "required", message: "Email required" },
  { type: "email", message: "Invalid format" }
]

Built-in Validators:

• required - Non-empty
• email - Valid email format
• minLength / maxLength - Character limits
• pattern - Regex matching
• match - Match another field
• number - Numeric only
• url - Valid URL
• phone - 10-digit phone
• custom - Your own logic

Common Use Cases

Password Confirmation

[
  { name: "password", type: "password", label: "Password" },
  { 
    name: "confirmPassword", 
    type: "password",
    label: "Confirm Password",
    validators: [
      { type: "match", matchField: "password", message: "Passwords don't match" }
    ]
  }
]

Async Validation

Check username availability, email existence, etc:

{
  name: "username",
  validators: [{
    type: "custom",
    message: "Username taken",
    custom: async (value) => {
      const res = await fetch(`/api/check?user=${value}`);
      return res.ok;
    }
  }]
}

Validation Timing

// Validate while typing (300ms debounce)
<DynamicForm validationMode="onChange" />

// Validate on blur (default)
<DynamicForm validationMode="onBlur" />

// Validate only on submit
<DynamicForm validationMode="onSubmit" />

Select & Radio Fields

{
  name: "country",
  type: "select",
  label: "Country",
  options: [
    { value: "us", label: "United States" },
    { value: "uk", label: "United Kingdom" }
  ]
}

Advanced Features

Custom Validation

Access form data and run any logic:

{
  type: "custom",
  message: "Error message",
  custom: (value, allFormData) => {
    // Return true if valid, false if invalid
    return value.length > 3 && !value.includes('@');
  }
}

Async Form Submission

<DynamicForm
  onSubmit={async (values) => {
    await saveToAPI(values);
  }}
  submitThrottleMs={1500}  // Prevent double-submit
/>

Supported Input Types

Text: text, email, password, number, tel, url, date
Complex: textarea, select, checkbox, radio

Props Reference

🎨 Theming

FormGuardian comes with 8 beautiful themes:

| Theme | Style | Primary Color | Best For | |-----------|--------------|--------------|-------------------------| | modern | Vibrant blue | #1e40af | Default, all-purpose | | dark | Dark mode | #f43f5e | Night, accessibility | | minimal | Minimalist | #d946ef | Clean, distraction-free | | gradient | Gradient | #ec4899 | Modern, creative | | ocean | Blue/teal | #0ea5e9 | Calm, professional | | sunset | Orange/pink | #f97316 | Warm, friendly | | purple | Purple/pink | #a78bfa | Elegant, creative | | forest | Green/earthy | #059669 | Natural, organic |

Usage:

import { DynamicForm } from 'formguardian-react';

// Use a built-in theme by name (default is 'modern')
<DynamicForm theme="ocean" ... />

// Use a custom theme object
import { oceanTheme } from 'formguardian-react/themes';
<DynamicForm theme={oceanTheme} ... />

All themeable colors, spacing, and fonts are handled automatically. No extra setup required.

DynamicForm

| Prop | Type | Default | Description | |------|------|---------|-------------| | fields | FieldConfig[] | Required | Form field definitions | | onSubmit | function | Required | Submit handler | | validationMode | 'onChange' \| 'onBlur' \| 'onSubmit' | 'onBlur' | When to validate | | submitButtonText | string | 'Submit' | Submit button label | | submitThrottleMs | number | 1000 | Throttle between submits | | disabled | boolean | false | Disable entire form |

FieldConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | name | string | ✓ | Unique identifier | | type | string | - | Input type | | label | string | - | Field label | | validators | array | - | Validation rules | | required | boolean | - | Mark required | | placeholder | string | - | Placeholder text | | defaultValue | any | - | Initial value | | options | array | - | For select/radio |

Troubleshooting

Validators not running?
Ensure your field has a name, and validators use correct types ('required', not 'require')

Need to validate against another field?
Use { type: "match", matchField: "otherFieldName" }

Custom validator not working?
Must return boolean or Promise<boolean>

License

MIT © Himanshu Sinha