SuperForm 🚀

A lightning-fast, TypeScript-first validation and form state management library for React.

SuperForm provides a Zod-like schema builder with a powerful validation engine, seamlessly integrated with React hooks to manage form state, errors, and submission with ease.

✨ Features

• TypeScript-First: Full type inference from your schemas. No more manual type definitions.
• Zod-Like Syntax: Intuitive and chainable schema builder.
• Comprehensive Validation: Supports strings, numbers, booleans, objects, and arrays.
• Async Validation: Built-in support for asynchronous rules (e.g., checking if a username is taken).
• React Integration: Lightweight hooks (useForm, useField) for effortless form state management.
• Zero Dependencies: Lightweight and optimized for performance.

📦 Installation

# Using npm
npm install @silentcoderhi/superform

# Using yarn
yarn add @silentcoderhi/superform

🚀 Quick Start

1. Define your Schema

import { superform } from "@silentcoderhi/superform/core";

const loginSchema = superform.object({
  email: superform.string().email().min(5),
  password: superform.string().min(8),
  rememberMe: superform.boolean().true(),
});

// Infer types automatically!
type LoginData = typeof loginSchema._type;

2. Use in React

import { useForm } from "@silentcoderhi/superform/react";
import { loginSchema } from "./schema";

function LoginForm() {
  const { register, handleSubmit, errors, isSubmitting } = useForm(loginSchema);

  const onSubmit = (data) => {
    console.log("Form submitted:", data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <input {...register("email")} placeholder="Email" />
        {errors.email && <span>{errors.email}</span>}
      </div>

      <div>
        <input type="password" {...register("password")} placeholder="Password" />
        {errors.password && <span>{errors.password}</span>}
      </div>

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Logging in..." : "Login"}
      </button>
    </form>
  );
}

🛠 API Reference

Schema Builder (superform)

String Schema

superform.string()
  .email()           // Must be a valid email
  .min(length)       // Minimum characters
  .max(length)       // Maximum characters
  .async(asyncFn)    // Custom async validation

Number Schema

superform.number()
  .min(value)        // Minimum value
  .max(value)        // Maximum value
  .async(asyncFn)    // Custom async validation

Array Schema

superform.array(superform.string())  // Array of strings
  .min(length)       // Minimum elements
  .max(length)       // Maximum elements

Object Schema

superform.object({
  username: superform.string(),
  age: superform.number(),
})

React Hooks

useForm(schema)

The primary hook for managing form state.

• register(name): Returns props for input binding.
• handleSubmit(onSubmit): Form submission handler with validation.
• errors: Object containing field errors.
• values: Current form values.
• isSubmitting: Boolean indicating submission status.

useField(name)

Access specific field state within a FormContext.

🧪 Testing

We use Vitest for unit testing.

npm test

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.