Recommended way to manage async file upload state in a complex form

[bopazyn]

I'm looking for recommendations on the best way to manage asynchronous file upload state in a complex form.

Context

My setup looks like this:

1. I have an <input type="file">.
2. Once few filesares selected, they are uploaded to Amazon S3 immediately.
3. Form submission waits until all pending uploads have completed successfully.
4. Form validation requires the upload to succeed before the form can be submitted.
5. The file upload is only a small part of a much larger and more complex form.

Questions

1. Is it recommended to keep the upload state (e.g. pending, success, error, uploaded file metadata) inside the form state?
2. If not, what would be the recommended approach? Specifically, is there a solution that doesn't require lifting the upload state all the way up to the component that owns the useForm hook?

I'm mainly interested in understanding the recommended architecture and trade-offs for this scenario, especially when the upload logic is only one piece of a much larger form.

[initial-d]

I would not put every upload detail into React Hook Form state.

The pattern I usually use is:

• keep transient upload state close to the upload component: progress, pending requests, abort controllers, retry state, raw File objects;
• store only the final form value in RHF: uploaded file IDs/URLs/metadata that your backend expects on submit;
• use RHF errors/validation to reflect whether the upload field is currently valid.

So the form value might be something stable like:

type FormValues = {
  title: string
  attachments: Array<{
    key: string
    url: string
    name: string
    size: number
  }>
}

Then the upload field component can own its internal async state, but still write the successful result into RHF:

function AttachmentField() {
  const { setValue, setError, clearErrors, watch } = useFormContext<FormValues>()
  const attachments = watch('attachments') ?? []
  const [pending, setPending] = useState(0)

  async function onFiles(files: FileList) {
    setPending((n) => n + files.length)

    try {
      const uploaded = await uploadFilesToS3(files)
      setValue('attachments', [...attachments, ...uploaded], {
        shouldDirty: true,
        shouldValidate: true,
      })
      clearErrors('attachments')
    } catch (e) {
      setError('attachments', {
        type: 'upload',
        message: 'Upload failed. Please retry.',
      })
    } finally {
      setPending((n) => n - files.length)
    }
  }

  return /* input + progress UI */
}

You do not have to lift all upload state to the component that owns useForm. Wrap the form in FormProvider, then the upload field can call useFormContext() and stay self-contained.

For submit blocking, I would combine two checks:

1. RHF validation: require at least one successfully uploaded attachment, or whatever your business rule is.
2. Upload UI state: disable submit while pending > 0, because a pending upload is not yet a valid form value.

If multiple fields need to know whether any upload is pending, use a tiny colocated store/context for upload status. But I would still keep RHF focused on serializable, submitted values. That keeps dirty state, reset, validation, and submission much easier to reason about.

[V-Kozintsev]

Keeping progress/retries in the upload component and completed file metadata in RHF makes sense. Two things I'd change in the example above:

Read the latest attachments after the upload finishes. The attachments captured before await can be stale. If two batches overlap, whichever finishes last can overwrite the other:

const uploaded = await uploadFilesToS3(files);
const current = getValues('attachments') ?? [];

setValue('attachments', [...current, ...uploaded], {
  shouldDirty: true,
  shouldValidate: true,
});

Take getValues from useFormContext alongside setValue. If a reset or unmount can happen during upload, cancel or ignore that batch's result as well.

Gate submission in the handler, not just the button. A small upload context can expose waitUntilSettled() to the form without moving all upload state into useForm. The submit handler should await that first, stop if a required upload failed, and only then call handleSubmit(save). That way RHF validates and reads the completed attachment values, rather than an earlier snapshot. Prevent new uploads while this final submit step runs.

Also avoid blindly calling clearErrors('attachments') after every success: another batch may have failed. Validate against the current overall upload status instead.

RHF getValues / handleSubmit.