@explita/daily-toolset-form

A powerful and extensible React form hook for building scalable forms with Zod validation, persistence, and full control.

✨ Features

• ✅ Built-in Zod schema validation
• ✅ Controlled and uncontrolled modes
• ✅ Persistent form state via localStorage
• ✅ Field-level error handling and parsing
• ✅ Debounced input validation
• ✅ Works seamlessly with any UI library (e.g. shadcn/ui)

📦 Installation

npm install @explita/daily-toolset-form
# or
yarn add @explita/daily-toolset-form

🧪 Usage

import { z } from "zod";
import { useForm, Form, Field } from "@explita/daily-toolset-form";
import { Input } from "@/components/ui/input";

const schema = z.object({
  email: z.email({ error: "Invalid email" }),
  password: z
    .string()
    .min(6, { error: "Password must be at least 6 characters" }),
});

export default function LoginForm() {
  const form = useForm({
    schema,
    defaultValues: { email: "", password: "" },
    onSubmit: async (values) => {
      console.log("Submitted", values);
      // call server action here or perform an HTTP request
      // const response = await login(values)
      // return response
      return values;
    },
    onSuccess: (result, ctx) => {
      console.log("Success", result);
      // result is the result of onSubmit
      // ctx.reset(); - reset the form, you don't need this if resetOnSuccess is true
    },
    onError: (error, ctx) => {
      console.log("Error", error, ctx);
      // error - the error object (usually from schema or server)
      // ctx.setErrors({ email: "Email is required" }); - useful for server errors
    },
    persistKey: "login-form", // Optional – saves input across reloads
    errorParser: (msg) => msg, // Optional – customize error messages
    mode: "controlled", // Optional – "controlled" is the default
    resetOnSuccess: true, // Optional – clears the form on success
  });

  //Field meta is an object that contains the value, error, and hasError properties

  return (
    <Form use={form}>
      <Field name="email" label="Email" isRequired>
        {(props, meta) => <Input {...props} />}
      </Field>

      <Field name="password" label="Password" isRequired>
        {(props, meta) => <Input type="password" {...props} />}
      </Field>

      <button type="submit" disabled={form.isSubmitting}>
        Submit
      </button>
    </Form>
  );
}

🧩 API Overview

useForm(options)

| Option | Type | Description | | ---------------- | ------------------------------------- | ------------------------------------------- | | schema | ZodObject | Optional Zod schema for validation | | defaultValues | Partial<T> | Initial form values | | onSubmit | (values, formData) => Promise<void> | Async submission handler | | onSuccess | (result) => void | Called on successful submission | | onError | (error, ctx) => void | Called on error, with access to setErrors | | persistKey | string | Key to store form values under | | errorParser | (msg: string) => string | Optional formatter for error messages | | mode | controlled|uncontrolled | Default to controlled | | resetOnSuccess | boolean | Clear the form on successful submission |

useFormContext()

Can be used in any component nested inside the Form component to access the form context.

📄 License

MIT — Made with ❤️ by Explita