Form Hook

#useForm() Hook

Sets up the form hook.

function useForm<Values extends FormValues>(
    initialValues: Values,
    onSubmit: (values: Values) => void | Promise<void>,
    options: FormOptions<Values> = {}
): FormiteForm<Values>
Copy

#Parameters

FormiteForm<Values>

The forms state and API

#Remarks

All initial field values should be set even if they are undefined.

#Form Options

Options for the Form Hook.

type FormOptions<Values extends FormValues> = {
    validateInitialValues?: boolean;
    validateOnBlur?: boolean;
    validateOnChange?: boolean;
    onValidate?: ValidateFormHandler<Values>;
};
Copy

#Form Validation

Function to validate the entire form.

type ValidateFormHandler<VALUES> = (
    values: VALUES,
    fields: Fields<VALUES>,
    setFieldError: (field: Field, error?: string) => void
) => string[] | Promise<string[]>;
Copy

#Remarks

The function receives the form's current values and should return an empty array if the values are valid. Otherwise the function should return an array of error messages. You can also set errors on individual fields by calling setFieldError(). If validation is asynchronous the function should return a Promise.

#Form State and API

State and API of the form returned by the useForm() hook.

interface FormiteForm<Values extends FormValues = FormValues> {
    readonly canSubmit: boolean;
    readonly fields: Fields<Values>;
    readonly formErrors: string[];
    readonly isDirty: boolean;
    readonly isSubmitting: boolean;
    readonly isValid: boolean;
    readonly isValidating: boolean;
    reset: () => void;
    setFieldTouched: (field: Field, touched: boolean) => void;
    setFieldValue: (field: Field, v: any, validate?: boolean) => Promise<boolean>;
    submit: () => Promise<boolean>;
    updateFields: (updateAction: (newFields: Fields<Values>) => void) => void;
    validate: () => Promise<boolean>;
}
Copy

#Properties

#useField() Hook

Sets up a form's field hook.

function useField(
    field: Field,
    onValidate?: ValidateFieldHandler,
    metadata?: any
): FormiteField
Copy

#Parameters

FormiteField

The fields state and API.

#Field Validation

Function to validate a single field's value.

type ValidateFieldHandler = (value: any, field: Field) => string | undefined | Promise<string | undefined>;
Copy

#Remarks

The function receives the current value of the field and should return undefined or an empty string if the value is valid. Otherwise the function should return an error message. If validation is asynchronous the function should return a Promise.

#Field State and API

State and API of an individual field returned by the useField() hook.

interface FormiteField {
    readonly value: any;
    onBlur: () => void;
    onChange: (value: any) => void;
}
Copy

#Properties

#Field

A form's field with its current state.

class Field<T = any> {
    readonly error: string | undefined;
    readonly initialValue: T;
    readonly isValidating: boolean;
    readonly name: string;
    readonly touched: boolean;
    readonly value: T;
    readonly visibleError: string | undefined;
    metadata: any;
}
Copy

#Properties

#Remarks

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Field class.

#createFields() function

Creates Field instances for all properties of the given object.

function createFields<VALUES extends FormValues>(object: VALUES): Fields<VALUES>;
Copy

#Parameters

Fields<VALUES>

An object with fields and arrays of fields with the same structure as the input object

#Remarks

Makes a deep copy of all values and arrays and creates new Field instances. This function is only used when using dynamic forms.

#clearFieldErrors() function

Clears the errors of the fields by doing a deep traversal.

function clearFieldErrors<VALUES extends FormValues>(fields: Fields<VALUES>): void;
Copy

#Parameters

#Remarks

For example, it can be used during form validation to clear all errors before setting field errors.