API Reference

Every export of gform-react - the components, hook, and validator class, plus the shared state types they pass around.

The package's public surface is exactly what gform-react exports. This page is the flat index: every export with a one-line summary and a link to its guide, followed by the shared types - the form- and field-state shapes the guides refer back to.

import {
  GForm,
  GInput,
  GValidator,
  useFormSelector,
  type GValidators,
  type GFormProps,
  type GFormState,
  type RNGFormState,
  type GInputProps,
  type GInputState,
  type GElementProps,
} from "gform-react";
 
// React Native entry
import { RNGForm, RNGInput } from "gform-react/native";

Exports

Export	Kind	What it does	Full guide
`GForm<T>`	Component	Form container - owns the state store, registers every field, renders a real `<form>` (native submit, reset, and Server Actions included). Accepts all `<form>` attributes plus the gform props.	GForm
`GInput`	Component	One field, identified by `formKey`. Renders a wired native `<input>` by default, or anything via the `element` render prop. Props are discriminated by `type`.	GInput
`GValidator<T>`	Class	Builds one field's rules - chainable constraint-message methods plus custom/async validators. Pass a base to the constructor to inherit its rules.	GValidator
`useFormSelector`	Hook	Subscribe a component inside a `GForm` to a slice of form state; it re-renders only when that slice changes.	useFormSelector

Each export's props are documented in full on its guide: GFormProps<T> on GForm, GInputProps on GInput, and the complete GValidator method list on GValidator. For Server Actions, pass action={formAction} to GForm instead of onSubmit - see Server Actions.

Types

These are the shapes the components and hook pass around - what onSubmit, the render prop, element, and useFormSelector receive. The guides above link here for the full shape.

`GFormState<T>` / `RNGFormState<T>`

The live form state. RNGFormState is the React Native variant - identical except it has no toFormData() (no native <form> on mobile).

Member	Description
`state.<formKey>`	The field's `GInputState`.
`state.isValid` / `state.isInvalid`	Whole-form validity.
`state.toRawData(options?)`	`{ [formKey]: value }` for the whole form.
`state.toFormData(options?)`	`FormData` instance (web only; includes files).
`state.toURLSearchParams(options?)`	`URLSearchParams` instance.
`state.checkValidity()`	Runs all validators; returns whether the form is valid.
`state.dispatchChanges(changes)`	Programmatically update one or more fields.

Options for toRawData / toFormData / toURLSearchParams:

{
  exclude?: (keyof T)[];
  include?: (keyof T)[];
  transform?: { [key in keyof T]?: (value) => any };
}

`GInputState<T>`

A single field's state - what element and useFormSelector receive.

Member	Description
`value`	The field's typed value.
`error`	Whether the field currently has an error.
`errorText`	The current error message.
`formKey`	The field's key.
`dirty` / `touched`	Interaction flags.
`checkValidity()`	Validate just this field.
`dispatchChanges(changes, options?)`	Update the field; `{ validate: true }` re-runs rules.

`GElementProps<T>`

The props object GInput hands to its element render prop. It's the intersection of <input>, <select>, and <textarea> attributes, so it spreads onto any of them without a cast, and it carries every pass-through prop you set on the GInput. onChange and ref are injected at runtime - don't override them. Because pass-through props land here, per-field attributes belong on GInput rather than inside the render prop:

<GInput
  formKey="title"
  placeholder="e.g. Land FAANG Position"
  element={(input, props) => <input {...props} />} // props includes the placeholder
/>

`GValidators<T>`

The formKey → GValidator map passed to GForm. "*" is the default entry for fields without one.

type GValidators<T> = { [key in keyof T]?: GValidator<T> } & {
  [key: string]: GValidator<T> | undefined; // '*' default + dynamic keys
};

`GFormProps<T>` / `GInputProps`

The component prop types - documented in full on GForm and GInput.

React Native exports

Export	Web analogue	Notes
`RNGForm`	`GForm`	Requires an `el` prop (container, e.g. `View`).
`RNGInput`	`GInput`	`element` receives `TextInputProps`; defaults to `TextInput`.

See React Native for a full example.