[form] Document onSubmit event handler alongside action

[aurorascharff]

Overview

The <form> reference page documented form submission only through the action prop. The classic event-handler approach — onSubmit + e.preventDefault() + new FormData(e.target) — was missing entirely, even though it's still fully valid and is the pattern shown on every related page (<input>, <select>, <textarea>, and throughout Learn).

This left readers with the impression that action is the only way to handle submission on the client, which isn't true.

Changes

• Add a new first Usage section, "Handle form submission with an event handler", showing the onSubmit pattern (matching the example style already used on the <input>/<select>/<textarea> pages).
• Add a <Note> contrasting the two approaches: onSubmit works in every version and gives direct event access; action builds on it with form resets, useFormStatus, and Server Functions.
• Rename "Handle form submission on the client" → "Handle form submission with an action" and clarify that an action runs in a Transition and doesn't need preventDefault().

The Server Function, pending state, optimistic update, error handling, and multiple-submission sections are genuinely action-specific and left unchanged.

[github-actions]

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[Copilot]

Pull request overview

This PR updates the <form> reference page to document classic client-side form submission via onSubmit (with preventDefault() + FormData), alongside the existing action-first approach, to avoid implying that action is the only valid client-side pattern.

Changes:

• Added a new first Usage section: “Handle form submission with an event handler” with an onSubmit + FormData Sandpack example.
• Added a <Note> contrasting onSubmit vs action (event access vs enhanced features like useFormStatus and Server Functions).
• Renamed and clarified the existing client submission section to be explicitly about action, including that it runs in a Transition and doesn’t need preventDefault().

Docs review checklist (docs-writer-reference / docs-voice / docs-components / docs-sandpack)

• docs-writer-reference

  • form.md:63-66 — Example style differs from the established onSubmit + FormData pattern used on related pages (store e.target in form before new FormData(form)).
  • form.md:86 — Heading could be clearer by explicitly referencing the action prop (to avoid reading as the HTML action attribute).

• docs-voice

  • form.md:82 — Use singular “pending state” (matches the rest of the page’s phrasing).

• docs-components

  • form.md:80-84 — <Note> spacing/structure matches component rules (blank line after opening tag, no consecutive callouts introduced).

• docs-sandpack

  • form.md:57-76 — Sandpack uses export default, function declarations, and e as event parameter; no hydration pitfalls observed.

Please create a plan to address the unchecked items above.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.