Capítulo 107 de 456

Form Component

Core Idea

<Form> (next/form) estende o <form> HTML com prefetching de loading UI, navegação client-side no submit e progressive enhancement. Ideal para formulários que atualizam search params na URL, reduzindo boilerplate.

Key Concepts

  • action string: comporta-se como form HTML nativo GET; dados viram search params na URL; Next.js faz prefetch do path quando o form entra na viewport e navegação client-side no submit (sem full reload).
  • action function (Server Action): comporta-se como React form, executando a action no submit; não suporta prefetch porque o destino não é conhecido antes da execução.
  • replace/scroll/prefetch: props só válidas quando action é string; ignoradas quando action é função.
  • formAction: override pontual em <button>/<input type="submit">, mas sem suporte a prefetch.

Code Examples

import Form from 'next/form'

export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}
  • O que demonstra: form de busca com action string, dados viram ?query=abc na URL do submit.
import Form from 'next/form'
import { createPost } from '@/posts/actions'

export default function Page() {
  return (
    <Form action={createPost}>
      <input name="title" />
      <button type="submit">Create Post</button>
    </Form>
  )
}
  • O que demonstra: mutação via Server Action passada como action função, seguida de redirect() dentro da action.

Reference Tables

Prop (action string)ExampleTypeRequired
actionaction="/search"string (URL ou path relativo)Sim
replacereplace={false}boolean (default false)-
scrollscroll={true}boolean (default true)-
prefetchprefetch={true}boolean (default true)-
Prop (action function)ExampleTypeRequired
actionaction={myAction}function (Server Action)Sim

Anti-patterns

  • method, encType, target no <Form>: não são suportados, sobrescrevem o comportamento do componente; use <form> HTML nativo se precisar deles.
  • onSubmit com event.preventDefault(): cancela a navegação/comportamento do <Form>.
  • key numa action string: não suportado; use action função se precisar forçar re-render/mutação.
  • <input type="file"> com action string: submete só o filename, não o arquivo, igual ao comportamento nativo do browser.
  • Esquecer basePath no formAction: se o projeto usa basePath, o path do formAction precisa incluí-lo manualmente.

Key Takeaways

  1. Use action string para forms de busca/filtro (atualiza URL, prefetch automático); use action função para mutações via Server Action.
  2. Combine com loading.js na rota de destino e/ou useFormStatus para feedback imediato de submit.
  3. Após mutação, redirecione manualmente com redirect() do next/navigation, o <Form> não faz isso sozinho.

Connects To

  • Components (ch105): índice dos componentes built-in.
  • Link Component (ch109): outra forma de navegação client-side com prefetch.
AnteriorFontPróximoImage Component