useForm() hook

Use this hook to access values and methods from a <Formiz> component.

Usage from outside <Formiz>

1. Connect your form

import React from 'react'
import { Formiz, useForm } from '@formiz/core'
import { MyField } from './MyField'
export const MyForm = () => {
const myForm = useForm()
return (
<Formiz connect={myForm}>
{/* Your fields here */}
</Formiz>
)
}

2. Access values and methods

You have now access to the form.

import React from 'react'
import { Formiz, useForm } from '@formiz/core'
import { MyField } from './MyField'
export const MyForm = () => {
const myForm = useForm()
return (
<Formiz connect={myForm}>
<form onSubmit={myForm.submit}>
{myForm.isValid && 'The form is valid!'}
{/* Your fields here */}
<button type="submit">
Submit
</button>
<form>
</Formiz>
)
}

Usage from a child component of <Formiz>

import React from 'react'
import { Formiz, useForm } from '@formiz/core'
import { MyField } from './MyField'
export const MySubComponent = () => {
const myForm = useForm()
return myForm.isValid && 'The form is valid!';
}
export const MyForm = () => {
return (
<Formiz>
...
<MySubComponent />
...
</Formiz>
)
}

Hook options

subscribe

TL;DR Use this option for performance optimization only

The subscribe option allows you to tell which part of the internal state you want to subscribe to. By default, you subscribe to the complete internal state. But for performance optimizations, you can choose exactly what you want.

Each time the internal state is updated, the component with the useForm() is updated. With this you can avoid many unecessary rerender and optimize your application by choosing only what you want to subscribe to.

Available values
// Subscribe to form & fields state (default)
useForm()
/* same as */ useForm({ subscribe: true })
/* same as */ useForm({ subscribe: { form: true, fields: true } })
// Subscribe to nothing (only access to form actions)
useForm({ subscribe: false })
/* same as */ useForm({ subscribe: { form: false, fields: false } })
// Subscribe to form state
useForm({ subscribe: 'form' })
/* same as */ useForm({ subscribe: { form: true } })
/* same as */ useForm({ subscribe: { form: true, fields: false } })
// Subscribe to fields state
useForm({ subscribe: 'fields' })
/* same as */ useForm({ subscribe: { fields: true } })
/* same as */ useForm({ subscribe: { form: false, fields: true } })
// Subscribe to form state & only to some fields
useForm({ subscribe: { form: true, fields: ['email', 'password'] } })
// Subscribe only to some fields
useForm({ subscribe: { fields: ['email', 'password'] } })

Form actions

The useForm return an object with the following properties:

submit()

Allow you to submit the form

<Formiz connect={myForm}>
<form onSubmit={myForm.submit}>
{/* Your fields here */}
<button type="submit">
Submit
</button>
</form>
</Formiz>

submitStep()

Allows you to submit the current step.

<Formiz connect={myForm}>
<form onSubmit={myForm.submitStep}>
<FormizStep name="step1">
{/* Your fields here */}
</FormizStep>
<FormizStep name="step2">
{/* Your fields here */}
</FormizStep>
<button type="submit">
Submit
</button>
</form>
</Formiz>

invalidateFields(objectOfErrors)

Allow you to invalidate one or many fields.
Useful for API errors or other external errors.

invalidateFields({
'fieldName': 'My error message',
'secondFieldName': 'Another error message',
})

setFieldsValues(objectOfValues)

Allow you to change the value of one or many fields imperatively.
Useful to change one or many values based on an external action.

⚠️ Don't use undefined as new value, it will not trigger the update (use null instead).

setFieldsValues({
'fieldName': 'New value',
'secondFieldName': 'Another new value',
})

reset()

Allows to reset the form with all fields values to their defaultValue.

const myForm = useForm()
myForm.reset() // Trigger the form reset

getFieldStepName(fieldName)

Allows you to get the step name of a field.

const myForm = useForm()
const stepNameOfEmail = myForm.getFieldStepName('email')
myForm.goToStep(stepNameOfEmail) // Navigate to the email field step

nextStep()

Move to the next step.

const myForm = useForm()
myForm.nextStep() // Go to the next step

prevStep()

Move to the previous step.

const myForm = useForm()
myForm.prevStep() // Go to the previous step

goToStep(name)

Go to a specific step.

const myForm = useForm()
myForm.goToStep('my-step') // Go to the step with the name 'my-step'

Form state

isValid

Returns true if the form is valid.

const myForm = useForm()
myForm.isValid // true or false

isValidating

Returns true if one field or more is running async validations.

const myForm = useForm()
myForm.isValidating // true or false

isSubmitted

Returns true if the form is submitted.

const myForm = useForm()
myForm.isSubmitted // true or false

resetKey

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

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

currentStep

Returns the current step object.

// currentStep properties
{
index: number;
name: string;
label?: React.ReactNode;
isCurrent: boolean;
isPristine: boolean;
isValid: boolean;
isValidating: boolean;
isVisited: boolean;
isSubmitted: boolean;
}
const myForm = useForm()
myForm.currentStep?.name // step-name

steps

Returns an array with all the steps of the form.

// Properties for each steps
{
index: number;
name: string;
label?: React.ReactNode;
isCurrent: boolean;
isPristine: boolean;
isValid: boolean;
isValidating: boolean;
isVisited: boolean;
isSubmitted: boolean;
}
const myForm = useForm()
return (
<ul>
{myForm.steps?.map((step) => (
<li key={step.name}>
{step.isValid ? '✅' : '❌'}
{' '}
{step.label || step.name}
</li>
))}
</ul>
)

isStepPristine

Returns true if all the fields are pristine on the current step.

const myForm = useForm()
myForm.isStepPristine // true or false

isStepValid

Returns true if all the fields are valid on the current step.

const myForm = useForm()
myForm.isStepValid // true or false

isStepValidating

Returns true if one field or more is running async validations on the current step.

const myForm = useForm()
myForm.isStepValidating // true or false

isStepSubmitted

Returns true if the current step is submitted.

const myForm = useForm()
myForm.isStepSubmitted // true or false

isFirstStep

Returns true if the current step is the first step.

const myForm = useForm()
myForm.isFirstStep // true or false

isLastStep

Returns true if the current step is the last step.

const myForm = useForm()
myForm.isLastStep // true or false

Fields state

values

Returns an object with all the values of the form with nested values.
See the name props for fields for nested objects and array values.

const myForm = useForm()
myForm.values
/*
{
fieldA: 'field A value',
nested: {
fieldB: 'field B value',
},
collection: [
{ field: 'collection first value' },
{ field: 'collection second value' },
],
}
*/

flatValues

Returns an object with all the values of the form without nested values.

const myForm = useForm()
myForm.flatValues
/*
{
fieldA: 'field A value',
'nested.fieldB': 'field B value',
'collection[0].field': 'collection first value',
'collection[1].field': 'collection second value',
}
*/

fields

Returns an object with all the fields of the form with their hook values.
See the name props for fields for nested objects and array syntaxe.
See the useField() hook values for available values.

const myForm = useForm()
myForm.fields
/*
{
fieldA: {
errorMessage: 'Required',
isValid: false,
value: 'My value',
// ... All useField hook values
},
nested: {
fieldB: {
// All useField hook values
},
},
collection: [
{
field: {
// All useField hook values
},
},
{
field: {
// useField hook values
},
  },
],
}
*/
// Examples
myForm.fields?.fieldA?.isValid
myForm.fields?.nested?.fieldB?.errorMessage
myForm.fields?.collection?.[0]?.field?.isPristine