useField() hook

Concept

When using the useField hook, you need to pass your component props to the hook.

Then the hook gives you access to the field state.

import React from 'react'
import { useField } from '@formiz/core'
const MyField = (props) => {
const {
value,
setValue,
isValid,
errorMessage,
} = useField(props)
return (
...
)
}

Hook values

The useField return an object with the following properties:

value

Get the current value of the field.

valueDebounced

Get the current value of the field, but sync with the debouncing. It can be useful to determinate when to show error messages.

setValue()

Set the value of the field.

id

Return a unique id.

<label htmlFor={id}>...</label>
<input id={id} />

isValid

Returns true if the field is valid.

isPristine

Returns true if the field has not been changed.

isSubmitted

Returns true either if the current step or the form is submitted.

errorMessage

Returns the first error message.

errorMessages

Returns all error messages.

resetKey

Allows you to put a key on elements that you want to be reinitialize when the from is reset.
Can be useful for element like <input> or <select>.

<input key={resetKey} />

Field props

When a component is created with the useField() hook, you can pass the following props to the component.

name *

Required

The name is required to register the field in the form.

<Field name="myFieldName" />

Nested objects

The name props can use lodash-like dot paths to reference nested values.

<Field name="fieldA" />
<Field name="fieldB" />
<Field name="myGroup.fieldA" />
<Field name="myGroup.fieldB" />
/* Form values
{
fieldA: 'value',
fieldB: 'value',
myGroup: {
fieldA: 'value',
fieldB: 'value',
},
}
*/

Arrays

The name props allow also arrays and arrays of objects out of the box. Using lodash-like bracket syntax for name allow you to handle fields in a list.

<Field name="myArray[0]" />
<Field name="myArray[1]" />
<Field name="myArrayOfObjects[0].fieldA" />
<Field name="myArrayOfObjects[0].fieldB" />
<Field name="myArrayOfObjects[1].fieldA" />
<Field name="myArrayOfObjects[1].fieldB" />
/* Form values
{
myArray: ['value', 'value'],
myArrayOfObjects: [
{ fieldA: 'value', fieldB: 'value' },
{ fieldA: 'value', fieldB: 'value' },
],
}
*/

debounce

Number of milliseconds for debouncing validations. (default is 100).

<Field name="myFieldName" debounce={200} />

defaultValue

Pass an initial value to the field.

<Field name="myFieldName" defaultValue="My initial value" />

keepValue

Set to true to keep the value when the field is unmounted from the DOM. (default is false).

formatValue(fieldValue)

Format the value before saving it into the internal state.

onChange(fieldValue)

Triggered everytime that setValue() is called inside the field.

<Field name="myFieldName" onChange={val => console.log(val)} />

required

Shortcut for isRequired() validation

<Field name="myFieldName" required />
<Field name="myFieldName" required="Field is required" />

validations

An array of object with:

  • rule(fieldValue, formValues): Built in validation rule or custom validation function (must return true if the rule is valid).
  • deps: Array of external values used in the rule function (like array of dependencies in useEffect).
  • message: The message if the rule is invalid.
<Field
name="myFieldName"
validations={[
{
rule: isRequired(),
message: 'Field is required',
},
{
rule: isNotEmptyString(),
message: 'Field can\'t be empty',
},
{
rule: (value) => value.toLowerCase() !== 'john',
message: 'Field can\'t be john',
},
{
rule: (value) => value !== externalValue,
deps: [externalValue],
message: 'Field can\'t be the same as external value',
},
]}
/>

PropTypes validations

If you using prop-types to document props in your project, you can get fieldPropTypes and fieldDefaultProps from @formiz/core to pass to your custom fields for PropTypes validations.

// MyField.js
import React from 'react'
import { useField, fieldPropTypes, fieldDefaultProps } from '@formiz/core'
const MyField = (props) => {
// ...
}
MyField.propTypes = {
...fieldPropTypes,
// Your custom props
}
MyField.defaultProps = {
...fieldDefaultProps,
// Your custom props
}