We wanted a simple forms API, so I built my own library

| is that it should feel closer to writing HTML than to configuring a library.

You write an input the way you'd write any other React component. At its simplest, gform renders a native <input>, and standard attributes like className and placeholder go right on GInput, which forwards them through:

<GInput formKey="email" type="email" required className="input" placeholder="Email" />

Need custom markup or inline errors? Pass an element. You spread props onto your input like you always would, and input.error and input.errorText are right there where you're rendering it, so no digging into formState.errors.email?.message, no Controller and no resolver setup:

<GInput formKey="email"

    type="email"

    required

    placeholder="Email"

    element={(input, props) => (

        <div>

            <input {...props} />

            {input.error && <small>{input.errorText}</small>}

        </div>

    )}

/>

Standard input attributes belong on GInput (they're forwarded either way); keep custom props on your element.

Dependent fields are where it actually hurts

Almost every real form has at least one. A city dropdown that only makes sense once you've picked a country, a street list that reloads when the city changes, that sort of thing.

The usual way to handle this looks something like:

const [cities, setCities] = useState([]);

const [loading, setLoading] = useState(false);

const country = watch("country");



useEffect(() => {

    if (!country) return;

    setLoading(true);

    loadCities(country).then((cities) => {

        setCities(cities);

        setValue("city", cities[0]);

        setLoading(false);

    });

}, [country]);

It works, but none of it actually lives in the form. It's wired together outside it, in your component, with a pile of useState and duct tape.

So I came up with another solution:

<GInput formKey="city"

    fetchDeps={["country"]}

    fetch={async (input, fields) => {

        const cities = await loadCities(fields.country.value);

        return { options: cities, value: cities[0] };

    }}

    element={renderCity}

/>

fetchDeps watches the country field. When it changes, fetch runs, loads the new cities, and pushes the result back into form state for you. The dependency tracking and the dispatch live inside the form instead of in your component.

Adding custom data to a field

That fetch attaches data automatically. You can do the same by hand with dispatchChanges: it merges whatever you give it onto the field's state, so you can park extra data there: a list of options, a loading flag, a label, whatever. then read it straight back in element.

Say you've loaded a city list and want to keep the selected value and the options together on the field:

state.city.dispatchChanges({

    value: cities[0],

    options: cities, // custom data, rides along on the field

});

Then read it where you render the input:

<GInput formKey="city"

    element={(input, props) => (

        <select {...props}>

            {input.options?.map((c) => (

                <option key={c} value={c}>{c}</option>

            ))}

        </select>

    )}

/>

No extra useState, no second source of truth. Add { validate: true } as a second argument if you passed a new value and if it should re-run validation.

What about native submission and Next.js Server Actions?

Native <form> submission and Next.js Server Actions work without any extra wiring. Submit through action instead of onSubmit, and gform still runs your client validation first and blocks an invalid submit before it ever reaches the server:

<GForm action={myServerAction}>

    <GInput formKey="email" type="email" required element={/* render input */} />

    <button>Submit</button>

</GForm>

Validation

Native HTML constraints (required, minLength, pattern, type, and the rest) work out of the box. The only thing you add is the message. Here's a full subscribe form:

import {GForm, GInput, GValidator} from "gform-react";



interface ISubscribeForm {

    name: string;

    email: string;

}



const baseValidator = new GValidator().withRequiredMessage(input => `${input.name} is required`);



// '*' is the default for every field; a message can be a string or a function

const validators = {

    "*": baseValidator,

    name: new GValidator(baseValidator).withMinLengthMessage("At least 2 characters"),

    email: new GValidator(baseValidator).withPatternMismatchMessage("Enter a valid email")

};



export const SubscribeForm = () => {

    return (

        <GForm<ISubscribeForm>

            validators={validators}

            onSubmit={(state, e) => {

                e.preventDefault();

                console.log(state.toRawData()); // { name, email }

            }}>

            {(state) => (

                <>

                    <GInput formKey="name"

                        required

                        minLength={2}

                        placeholder="Name"

                        element={(input, props) => (

                            <div>

                                <input {...props} />

                                {input.error && <small>{input.errorText}</small>}

                            </div>

                        )}

                    />

                    <GInput formKey="email"

                        type="email"

                        required

                        pattern="[^@\s]+@[^@\s]+\.[^@\s]+"

                        placeholder="Email"

                        element={(input, props) => (

                            <div>

                                <input {...props} />

                                {input.error && <small>{input.errorText}</small>}

                            </div>

                        )}

                    />

                    <button disabled={state.isInvalid}>Subscribe</button>

                </>

            )}

        </GForm>

    );

}

The pattern on email is enough for gform to show your patternMismatch message instead of the browser's generic typeMismatch (pattern wins when both fail). A message can be a plain string or a function of the input, and "*" applies a validator to every field unless you override it, the way email does here.

Need a rule native HTML can't express? Add a custom check. You return true to mark the field invalid (you're answering "is this broken?"), and set the message on input.errorText:

const validators = {

    fullName: new GValidator().withCustomValidation((input) => {

        input.errorText = "please pick another name";

        return input.value === "admin"; // true means invalid

    })

};

Prefer a schema? Hand withSchema a Zod, Valibot, or ArkType, Joi, or any other library that implements - any library implementing the spec works out of the box (Zod, Valibot, ArkType, Yup, …); drive the whole form from one schema via GValidator.withSchema / withSchemaAsync, including object-level cross-field rules - with zero runtime dependencies

The honest part

gform-react was a private library. There aren't years of tutorials, a pile of Stack Overflow answers, or a big ecosystem around it. I built it because we needed it, we run it in production, and I fix the rough edges as we hit them.

If you're happy with your current setup, you probably don't need it.

But if you've ever stared at a form component and wondered why something this basic turned into this much code, it might be worth a look.