I’ve been integrating @tanstack/react-form with a Next.js Server Action and ran into an issue where the formData was coming in as null on the server side.

Turns out, it was because I didn’t explicitly set the name attribute on the actual HTML <input /> elements—only on the wrapper component. This tripped me up because the form composition example doesn’t include the name prop on the input field itself, while the Next.js Server Actions example does include it.

Here’s a minimal illustration of what was missing:

<form.AppField name="firstName">
  {(field) => <field.TextField label="First Name" />}
</form.AppField>

// text-field.tsx
import { useFieldContext } from './form-context.tsx'

export function TextField({ label }: { label: string }) {
  const field = useFieldContext<string>()
  return (
    <label>
      <div>{label}</div>
      <input
        name={field.name} // ✅ this is required for formData to work server-side
        // other props...
      />
    </label>
  )
}

In contrast, the form composition docs omit name={field.name} in the input, which led me to assume it was unnecessary or handled for us automatically:

// From docs (missing HTML name):
<input
  value={field.state.value}
  onChange={(e) => field.handleChange(e.target.value)}
  // name is not included here
/>

I totally understand this is just how HTML forms work — inputs need a name to be serialized in the POST request — but since form libraries often abstract away HTML standards, it wasn’t immediately obvious that this step was still required.

Suggestion:
It would be really helpful to add a small comment or note to the form composition guide or the Next.js Server Action guide that says something like:

💡 When using native form submission (e.g. with Next.js Server Actions), be sure to include the name attribute on your actual input fields, not just the <form.AppField name="..." /> wrapper.

I'd be happy to submit a PR. Just let me know what section of the docs you think this belongs in. Maybe both?

Thanks for all the hard work on TanStack Form and for the prompt communication on the Discord server — I'm really excited about this library!