Is it correct that useFieldArray does not support nullable arrays?

[jfulse]

Example type and default values:

type Values = { listField: { a: string }[] | null };
const defaultValues: DefaultValues<Values> = { listField: null };

When trying to use this with useFieldArray, the value in the form state immediately becomes an empty array. This leads to the form being marked as dirty, which is not good for our use case.

Question: Is there a way to handle nullable arrays without the form spuriously being marked as dirty, or do we have to make sure our model does not include nullable arrays?

I haven't been able to find much about this in docs etc, the clearest answer I've seen is in this discussion.

Below is a full reproduction, where we see that values.listField and defaultValues.listField are immediately different. If we remove the line with useFieldArray they are both null.

import { DefaultValues, useFieldArray, useForm } from "react-hook-form";

type Values = { listField: { a: string }[] | null };
const defaultValues: DefaultValues<Values> = { listField: null };

export default function Test() {
  const form = useForm<Values>({ defaultValues });
  useFieldArray({ control: form.control, name: "listField" });

  console.log("defaultValues:", form.formState.defaultValues);
  console.log("values:", form.getValues());

  return (<div><h1>Test</h1></div>);
}

[tejas-ae]

This is by design. useFieldArray normalizes null and undefined to [] internally because it needs a real array to track field objects. There is no config to disable this.

Two workarounds depending on what you need:

1. Keep null out of RHF, transform on submit:

handleSubmit((data) => {
  const payload = { ...data, listField: data.listField.length ? data.listField : null };
  submit(payload);
});

2. Skip useFieldArray entirely and use useWatch + setValue if preserving null in form state matters more than the field array helpers.

The issue you linked confirms this is a known limitation with no plans to change it.

[chrisjcthomas]

Yes, that is correct: useFieldArray requires an array to manage its internal fields, keys, and operations.

If your initial state or defaultValues for a field array contains null or undefined, useFieldArray will automatically initialize it to an empty array [] on mount so it can map over the fields. Because values.listField becomes [] while defaultValues.listField remains null, the deep comparison in formState.isDirty detects a difference and marks the form as dirty immediately.

Recommended Solution: Boundary Mapping

The idiomatic way to handle this is to avoid passing null arrays into the form state. Instead, map the data at the boundary of your component:

1. Map on Load: Initialize the field as an empty array [] in defaultValues.
2. Map on Submit: Convert the empty array [] back to null before sending it to your backend API.

Here is an example:

import { DefaultValues, useFieldArray, useForm } from "react-hook-form";

type Values = { listField: { a: string }[] }; // Keep array non-nullable in form types

// 1. Map null from API to [] for default values
const apiResponse = { listField: null };
const defaultValues: DefaultValues<Values> = { 
  listField: apiResponse.listField ?? [] 
};

export default function Test() {
  const form = useForm<Values>({ defaultValues });
  useFieldArray({ control: form.control, name: "listField" });

  const onSubmit = (data: Values) => {
    // 2. Map empty array back to null before sending to backend
    const payload = {
      ...data,
      listField: data.listField.length === 0 ? null : data.listField
    };
    console.log("Payload to API:", payload);
  };

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      {/* ... */}
      <button type="submit">Submit</button>
    </form>
  );
}

[BrendanC23]

There's a new disabled option that can help with this. Just pass disabled: list field === null to prevent useFieldArray from automatically initializing the array.

#13519

#13520