Capítulo 364 de 456

Form

Core Idea

<Form> (next/form) estende o <form> HTML nativo para oferecer navegação client-side e progressive enhancement em submissões, reduzindo boilerplate para formulários que atualizam search params na URL.

Key Concepts

  • action como string: <Form> se comporta como formulário HTML nativo com método GET — os dados viram search params na URL de destino, e Next.js faz navegação client-side (sem full reload) em vez de recarregar a página.
  • replace: substitui o estado atual do histórico do navegador em vez de empurrar um novo (default false).
  • scroll: controla comportamento de scroll na navegação (default true, sobe ao topo da nova rota).
  • action="": navega para a mesma rota com os search params atualizados.

Code Examples

import Form from 'next/form'

export default function Page() {
  return (
    <Form action="/search">
      {/* On submission: /search?query=abc */}
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}
  • O que demonstra: uso básico do <Form> com action string, gerando navegação com search params automaticamente.

Reference Tables

PropExemploTipoObrigatório
actionaction="/search"string (URL ou path relativo)Sim
replacereplace={false}boolean-
scrollscroll={true}boolean-

Anti-patterns

  • Usar method, encType ou target: não são suportados, pois sobrescrevem o comportamento de <Form>; usar formMethod/formEncType/formTarget faz cair no comportamento nativo do browser. Se precisar desses atributos, use <form> HTML puro.
  • Chamar event.preventDefault() em onSubmit: cancela a navegação/comportamento padrão do <Form>.
  • <input type="file"> com action string: submete apenas o nome do arquivo, não o objeto File (mesmo comportamento de um form HTML nativo GET).

Key Takeaways

  1. <Form> só documenta aqui o comportamento com action string (método GET); comportamento com action função não está nesta página-fonte.
  2. Navegação client-side preserva UI compartilhada e estado, ao contrário de um submit HTML puro.
  3. Métodos/encType/target nativos exigem cair de volta para <form> comum.

Connects To

  • next/link: mesma filosofia de navegação client-side sem reload completo.
  • getServerSideProps (ch357): search params gerados pelo <Form> frequentemente alimentam SSR de páginas de busca.
AnteriorFontPróximoHead