How to proper autofill with API data?

[GustavoOS]

The scenario:
I have a customer form with address fields, including a postal code using tanstack forms.
When the user types the postal auto code, I can trigger an API query, using tanstack query, and have that result autofill the rest of the address fields (when applicable).

The only way I can think of is using useEffect, but I think this looks wrong.

[Yuno15-bb]

You don't need useEffect for this: a field can have listeners, which run on the change event itself, and they support debouncing. From there you call TanStack Query imperatively with queryClient.fetchQuery (so lookups are still cached) and write the other fields with form.setFieldValue.

function CustomerForm() {
  const queryClient = useQueryClient()
  const form = useForm({
    defaultValues: { postalCode: '', street: '', city: '' },
  })

  return (
    <form>
      <form.Field
        name="postalCode"
        listeners={{
          onChangeDebounceMs: 400,
          onChange: async ({ value, fieldApi }) => {
            const code = value.replace(/\D/g, '')
            if (code.length !== 8) return

            const address = await queryClient.fetchQuery({
              queryKey: ['address', code],
              queryFn: () => fetchAddress(code),
              staleTime: Infinity,
            })
            if (!address) return

            // the user may have changed the postal code while the request was running
            if (fieldApi.state.value.replace(/\D/g, '') !== code) return

            fieldApi.form.setFieldValue('street', address.street)
            fieldApi.form.setFieldValue('city', address.city)
          },
        }}
      >
        {(field) => (
          <input value={field.state.value} onChange={(e) => field.handleChange(e.target.value)} />
        )}
      </form.Field>

      <form.Field name="street">
        {(field) => (
          <input value={field.state.value} onChange={(e) => field.handleChange(e.target.value)} />
        )}
      </form.Field>
      {/* city… */}
    </form>
  )
}

The listener only runs when the postal code changes, so the address fields stay editable after the autofill. fetchQuery returns the cached result if the same code was already looked up.

I checked this with @tanstack/react-form 1.33.5, @tanstack/react-query 5.103.1 and React 19 (jsdom + Testing Library, fake API):

• Typing the code one character at a time makes a single request, then fills street and city.
• Editing the street afterwards is not overwritten.
• A slow response for an old code doesn't overwrite the form once the code has changed. Without the check before setFieldValue, it does.
• Typing the same code again uses the cache, with no new request.

Docs: Listeners.