useForm

This hook creates a form, and returns it.

Import

import { useForm } from "@formiz/core";

Basic usage

const form = useForm();

Form values type

You can add a generic type param to useForm to help you using form actions.

type FormValues = { name: string };
 
const form = useForm<FormValues>();
 
form.setValues({ name: "" }); // ✅ ok, with autocompletion
form.setValues({ notName: "" }); // ❌ error

Form Config

id

Allows you to pass a custom id, which will be used to create the ids of the fields. The form will be reset when it changes. By default, it is generated automatically.

const form = useForm({ id: "custom-id" });

initialValues

Allows you to pass some initial values to the form. If a field is mounted, it will lookup into this object to set his initial value. This is usefull when you are getting data from an API like an edit page.

const form = useForm({ initialValues: { myField: "my initial value" } });

initialStepName

Allows you to define the initial step.

const form = useForm({ initialStepName: "step-2" });

ready

Allows you to delayed form setup, this can be usefull when you have async initialValues. If it is not defined, ready is true. Everytime ready turn from false to true, the form will be reset to its initial state.

const [data, setData] = useState();
const [isFetched, setIsFetched] = useState(false);
useEffect(() => {
  const dataFetch = async () => {
    const data = await (await fetch("/api/async-initial-values")).json();
    setData(data);
    setIsFetched(true);
  };
 
  dataFetch();
}, []);
 
const form = useForm({ ready: isFetched, initialValues: data });

stateSubscription

An object to manage form returned state

const form = useForm({ stateSubscription: [{ only: ["isValid"] }] });
form.isValid; // exists
form.isSubmitted; // doesn't exists
const form = useForm({ stateSubscription: [{ exclude: ["isValid"] }] });
form.isValid; // doesn't exists
form.isSubmitted; // exists

onSubmit(values)

Function triggered on form submission, whether it is valid or not.

const form = useForm({ onSubmit: (values) => console.log({ values }) });

onValidSubmit(values)

Function triggered on form submission, only if it is valid.

const form = useForm({ onValidSubmit: (values) => console.log({ values }) });

onInvalidSubmit(values)

Function triggered on form submission, only if it is invalid.

const form = useForm({ onInvalidSubmit: (values) => console.log({ values }) });

onValuesChange(values)

Function triggered on any form field value change.

const form = useForm({ onValuesChange: (values) => console.log({ values }) });

onValid()

Triggered when the form is valid.

const form = useForm({ onValid: () => console.log("form is valid") });

onInvalid()

Triggered when the form is invalid.

const form = useForm({ onInvalid: () => console.log("form is invalid") });

Form State

isValid

Return true if all form fields are valid, else return false.

const form = useForm();
form.isValid;

isValidating

Return true if at least one field is running async validations, else return false.

const form = useForm();
form.isValidating;

isSubmitted

Return true if the form has been submitted, else return false.

const form = useForm();
form.isSubmitted;

resetKey

A key that change when form is reset.

Allows you to reset some internal state when the form is reset.

const form = useForm();
useEffect(() => {
  /* Do a side effect on reset */
}, [form.resetKey]);

currentStep

The name of the current step.

const form = useForm();
form.currentStep;

steps

An array that contains all form steps.

const form = useForm();
form.steps;

isStepPristine

Return true if all current step fields are pristine, else return false.

const form = useForm();
form.isStepPristine;

isStepValid

Return true if all current step fields are valid, else return false.

const form = useForm();
form.isStepValid;

isStepValidating

Return true if at least one current step field is running async validations, else return false.

const form = useForm();
form.isStepValidating;

isStepSubmitted

Return true if the current step has been submitted, else return false.

const form = useForm();
form.isStepSubmitted;

isFirstStep

Return true if the current step is the first form step, else return false.

const form = useForm();
form.isFirstStep;

isLastStep

Return true if the current step is the last form step, else return false.

const form = useForm();
form.isLastStep;

Form Actions

submit()

Submit whole form.

const form = useForm();
form.submit();

submitStep()

Submit current step.

const form = useForm();
form.submitStep();

setErrors(errors)

Manually set errors on form fields.

const form = useForm();
form.setErrors({ field: "Error" });

setValues(values, options)

Manually set form fields values.

keepPristine option allows you to choose if setValues keep unchanged fields pristine state. By default, keepPristine is false

const form = useForm();
form.setValues({ field: "New value" }, { keepPristine: true });

reset(options)

Reset form's states and values. Options allows you to select the data you want to reset.

Available options: "pristine", "submitted", "touched", "validating", "debouncing", "resetKey", "currentStep", "visited", "values"

const form = useForm();
form.reset({ only: ["values"] });
form.reset({ exclude: ["pristine"] });

getStepByFieldName(fieldName)

Get step informations from field name.

const form = useForm();
const step = form.getStepByFieldName("field");

goToNextStep()

Navigate to next step.

const form = useForm();
form.goToNextStep();

goToPreviousStep()

Navigate to previous step.

const form = useForm();
form.goToPreviousStep();

goToStep(name)

Navigate to a step.

const form = useForm();
form.goToStep("step-2");

collection(fieldName)

Return methods to manage a field collection, see useCollection().

const form = useForm();
const portsCollection = form.collection("ports");
 
portsCollection.append({ number: "1234" }); // add an element to ports collection