rooks/dist/esm/hooks/useFormState.d.ts

Collection of awesome react hooks

import { ChangeEvent, FormEvent } from "react";
/**
 * Validation function type
 */
type ValidatorFunction<T> = (name: keyof T, value: any, values: T) => string | undefined;
/**
 * Options for the useFormState hook
 */
interface UseFormStateOptions<T> {
    /**
     * Initial form values
     */
    initialValues: T;
    /**
     * Validation function
     */
    validate?: ValidatorFunction<T>;
    /**
     * Callback when form is submitted with valid data
     */
    onSubmit?: (values: T) => void | Promise<void>;
}
/**
 * Return value for the useFormState hook
 */
interface UseFormStateReturnValue<T> {
    /**
     * Current form values
     */
    values: T;
    /**
     * Validation errors for each field
     */
    errors: Partial<Record<keyof T, string>>;
    /**
     * Touched state for each field
     */
    touched: Partial<Record<keyof T, boolean>>;
    /**
     * Whether the form is currently submitting
     */
    isSubmitting: boolean;
    /**
     * Whether the form is valid
     */
    isValid: boolean;
    /**
     * Handle input change events
     */
    handleChange: (event: ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
    /**
     * Handle form submit events
     */
    handleSubmit: (event: FormEvent<HTMLFormElement>) => void;
    /**
     * Set a specific field value
     */
    setFieldValue: (name: keyof T, value: any) => void;
    /**
     * Set a specific field error
     */
    setFieldError: (name: keyof T, error: string) => void;
    /**
     * Set a specific field as touched
     */
    setFieldTouched: (name: keyof T, touched: boolean) => void;
    /**
     * Reset the form to initial values
     */
    reset: () => void;
}
/**
 * useFormState hook
 *
 * Comprehensive form state management with validation and error handling.
 * Handles form values, errors, touched state, and submission.
 *
 * @param options - Configuration options for the form
 * @returns Object containing form state and handlers
 *
 * @example
 * ```tsx
 * import { useFormState } from "rooks";
 *
 * interface LoginForm {
 *   email: string;
 *   password: string;
 * }
 *
 * function LoginComponent() {
 *   const {
 *     values,
 *     errors,
 *     touched,
 *     isSubmitting,
 *     isValid,
 *     handleChange,
 *     handleSubmit,
 *     reset,
 *   } = useFormState<LoginForm>({
 *     initialValues: { email: "", password: "" },
 *     validate: (name, value, values) => {
 *       if (name === "email" && !value.includes("@")) {
 *         return "Invalid email";
 *       }
 *       if (name === "password" && value.length < 6) {
 *         return "Password must be at least 6 characters";
 *       }
 *     },
 *     onSubmit: async (values) => {
 *       await loginUser(values);
 *     },
 *   });
 *
 *   return (
 *     <form onSubmit={handleSubmit}>
 *       <input
 *         name="email"
 *         value={values.email}
 *         onChange={handleChange}
 *       />
 *       {touched.email && errors.email && <span>{errors.email}</span>}
 *
 *       <input
 *         name="password"
 *         type="password"
 *         value={values.password}
 *         onChange={handleChange}
 *       />
 *       {touched.password && errors.password && <span>{errors.password}</span>}
 *
 *       <button type="submit" disabled={!isValid || isSubmitting}>
 *         {isSubmitting ? "Submitting..." : "Login"}
 *       </button>
 *       <button type="button" onClick={reset}>Reset</button>
 *     </form>
 *   );
 * }
 * ```
 *
 * @see https://rooks.vercel.app/docs/hooks/useFormState
 */
declare function useFormState<T extends Record<string, any>>({ initialValues, validate, onSubmit, }: UseFormStateOptions<T>): UseFormStateReturnValue<T>;
export { useFormState };
export type { UseFormStateOptions, UseFormStateReturnValue, ValidatorFunction, };