Forms in React

What a form means in React

A form has three things to manage: the fields' values, the validation errors and the submission state (pending, success, a server error). React gives you two fundamental ways to hold the values, and every form library is built on one of them.

The HTML basics (name, label, input types, native validation) are in the HTML forms lesson — here we build on top of them.

Controlled vs uncontrolled

The difference between a controlled input and an uncontrolled one:

// controlled
const [email, setEmail] = useState('')
<input value={email} onChange={e => setEmail(e.target.value)} />

// uncontrolled
<input name="email" defaultValue={user.email} />

value without onChange = a locked (read-only) input. defaultValue = the initial value, then the DOM takes over.

Reading the data: FormData

function onSubmit(e: React.FormEvent<HTMLFormElement>) {
  e.preventDefault()
  const form = new FormData(e.currentTarget)
  const email = String(form.get('email'))
  const tags = form.getAll('tags')            // checkboxes with the same name → an array
  const data = Object.fromEntries(form)       // ⚠️ keeps only the last value for repeated names
}

FormData values are always strings (or a File). A checked checkbox sends 'on', an unchecked one doesn't appear at all.

React 19: forms with actions

React 19 lets you pass a function directly to action. React takes care of preventDefault, of FormData and of the pending state.

'use client'
import { useActionState } from 'react'
import { useFormStatus } from 'react-dom'

type State = { error?: string; ok?: boolean }

async function subscribe(prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get('email') ?? '')
  if (!email.includes('@')) return { error: 'Invalid email' }
  await api('/subscribe', { method: 'POST', body: formData })
  return { ok: true }
}

function SubmitButton() {
  const { pending } = useFormStatus()          // reads the parent form's state
  return <button disabled={pending}>{pending ? 'Sending…' : 'Subscribe'}</button>
}

export function Newsletter() {
  const [state, action] = useActionState(subscribe, {})
  return (
    <form action={action}>
      <input name="email" type="email" required />
      {state.error && <p role="alert">{state.error}</p>}
      <SubmitButton />
    </form>
  )
}

With a Server Action instead of the client function, the same form works even without JavaScript.

Accessible errors

An error has to be seen and heard:

<label htmlFor="email">Email</label>
<input id="email" name="email" aria-invalid={!!error} aria-describedby={error ? 'email-error' : undefined} />
{error && <p id="email-error" role="alert">{error}</p>}

When you need a library

Summary

• Uncontrolled + FormData for most forms; controlled when the value changes the UI live.
• React 19: action={fn}, useActionState for the result, useFormStatus for pending.
• Errors: aria-invalid + aria-describedby + role="alert".

Official sources

• react.dev — <form>
• react.dev — <input> (controlled)
• react.dev — useActionState
• react.dev — useFormStatus