useField

Hook methods

setValue()

(fieldValue : any) => void

Set the value of the field.

const MyField = (props) => {
  const { setValue } = useField(props);
 
  return <input onChange={(e) => setValue(e.target.value)} />;
};

setValue also accepts a function that takes the previous value as a parameter (like React setState).

setValue((previousValue) => {
  // ...
  // Your logic
  // ...
  return newValue;
});

setIsTouched()

(isTouched : boolean) => void

Set the value isTouched of the field.

const MyField = (props) => {
  const { setIsTouched } = useField(props);
 
  setIsTouched(true);
 
  return <input />;
};

Hook values

value

Get the current value of the field, after it has been formated by formatValue (if you used it).

const MyField = (props) => {
  const { value } = useField(props);
 
  return <input value={value ?? ""} />;
};

rawValue

Get the current value of the field, before it has been modified by formatValue.

const MyField = (props) => {
  const { rawData, value } = useField(props);
 
  return (
    <input value={value ?? ""} formatValue={(val) => (val || "").trim()} />
  );
  /* Differences between value and rawValue
  {
    value: 'value',
    rawValue: '     value',
  }
  */
};

id

number

Return a unique id. This id will be created based on the form id and the field name.

const MyField = (props) => {
  const { id } = useField(props)
 
  return (
    <label htmlFor={id}>...</label>
    <input id={id} />
  )
}

isTouched

boolean

Return true if the field has been touched.

const { isTouched } = useField(props);

isValid

boolean

Return true if the field is valid.

const { isValid } = useField(props);

isValidating

boolean

Return true if the field is running async validations.

const { isValidating } = useField(props);

isPristine

boolean

Return true if the field has not been changed.

const { isPristine } = useField(props);

isSubmitted

boolean

Return true either if the current step or the form has been submitted.

const { isSubmitted } = useField(props);

shouldDisplayError

boolean

Return true if the field should display an error, useful when debugging.

const { shouldDisplayError } = useField(props);

errorMessage

string | undefined

Return the first error message.

const { errorMessage } = useField(props);

errorMessages

string[] | undefined

Return all error messages.

const { errorMessages } = useField(props);

resetKey

number

Return the number of time the form has been reset.

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

Hook extra values

otherProps

Get the props passed to the component without the Formiz props. Allows you to keep composition by spreading this object in your component.

const MyField = (props) => {
  const { otherProps } = useField(props);
 
  return <Box {...otherProps}>{/* Field */}</Box>;
};

Field props

name *

string

Required

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

<Field name="myFieldName" />

Nested objects

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

Also allow arrays 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' },
  ],
}
*/

defaultValue

Pass a default value to the field.

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

formatValue(fieldValue)

(fieldValue) => string | null

Format the value before saving it into the internal state.

<Field name="myFieldName" formatValue={(val) => (val || "").trim()} />

onValueChange(fieldValue)

(fieldValue) => void

Callback function when the value of the field is changed.

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

required

boolean

Shortcut for isRequired() validation.

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

debounceValidationsAsync

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

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

validations

Add validation rules that the value needs to fulfill for the field to be considered valid.

Accept an array of object with the following keys:

• handler(value, rawValue): Built in validation rule or custom validation function (must return true if the rule is valid).
  • value references the value of the field.
  • rawValue references the value of the field before any formatting of the data via formatValue.
• deps: Array of external values used in the rule function (like array of dependencies in useEffect).
• message: The message if the rule is invalid.
• checkFalsy: When true (default false) validations will run even on falsy values (including null, undefined, '' and false).

<Field
  name="myFieldName"
  validations={[
    {
      handler: isNotEmptyString(),
      message: "Field can't be empty",
    },
    {
      handler: (value) => value.toLowerCase() !== "john",
      message: "Field can't be john",
    },
    {
      handler: (value) => value !== externalValue,
      deps: [externalValue],
      message: "Field can't be the same as external value",
    },
  ]}
/>

validationsAsync

Async validations allows you to run asynchronous code to validate a field, such as an API call. validationsAsync will only be triggered if all the other validations rules are valid.

Accept an array of object with the following keys:

• handler(fieldValue): Must return a Promise that 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"
  validationsAsync={[
    {
      handler: async (value) => {
        const isAlreadyUsed = await validateUsername(value);
        return isAlreadyUsed;
      },
      message: "Username already used, please select another one.",
    },
  ]}
/>

Field config

✨ formatValue

Awaiting contribution

✨ required

Awaiting contribution

✨ validations

Awaiting contribution

✨ validationsAsync

Awaiting contribution

✨ debounceValidationsAsync

#Awaiting contribution

✨ unstable_notifyOnChangePropsExclusions

Awaiting contribution