Formular

Die <Form>-Komponente erweitert das HTML-<form>-Element, um Prefetching von Lade-UI, clientseitige Navigation bei Übermittlung und progressive Verbesserung bereitzustellen.

Sie ist nützlich für Formulare, die URL-Suchparameter aktualisieren, da sie den Boilerplate-Code reduziert, der für die oben genannten Funktionen benötigt wird.

Grundlegende Verwendung:

import Form from 'next/form'

export default function Page() {
  return (
    <Form action="/search">
      {/* Bei Übermittlung wird der Eingabewert an die
          URL angehängt, z.B. /search?query=abc */}
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}

Referenz

Das Verhalten der <Form>-Komponente hängt davon ab, ob die action-Prop einen string oder eine function erhält.

• Wenn action ein String ist, verhält sich <Form> wie ein natives HTML-Formular, das eine GET-Methode verwendet. Die Formulardaten werden als Suchparameter in die URL kodiert, und bei Übermittlung des Formulars wird zur angegebenen URL navigiert. Zusätzlich führt Next.js folgendes aus:
  • Prefetching des Pfads, wenn das Formular sichtbar wird. Dies lädt die gemeinsame UI (z.B. layout.js und loading.js) vor, was zu schnellerer Navigation führt.
  • Führt eine clientseitige Navigation anstelle eines vollständigen Seitenneuladens durch, wenn das Formular übermittelt wird. Dies erhält die gemeinsame UI und den clientseitigen Zustand.
• Wenn action eine Funktion (Server Action) ist, verhält sich <Form> wie ein React-Formular und führt die Aktion bei Übermittlung des Formulars aus.

action (string) Props

Wenn action ein String ist, unterstützt die <Form>-Komponente folgende Props:

• action: Die URL oder der Pfad, zu dem bei Übermittlung des Formulars navigiert werden soll.
  • Ein leerer String "" navigiert zur gleichen Route mit aktualisierten Suchparametern.
• replace: Ersetzt den aktuellen Verlaufseintrag anstatt einen neuen zum Browserverlauf hinzuzufügen. Standard ist false.
• scroll: Steuert das Scrollverhalten während der Navigation. Standard ist true, was bedeutet, dass zur Oberseite der neuen Route gescrollt wird und die Scrollposition für Vor- und Zurück-Navigation beibehalten wird.
• prefetch: Steuert, ob der Pfad vorab geladen werden soll, wenn das Formular im sichtbaren Bereich des Benutzers erscheint. Standard ist true.

action (function) Props

Wenn action eine Funktion ist, unterstützt die <Form>-Komponente folgende Prop:

• action: Die Server Action, die bei Übermittlung des Formulars aufgerufen wird. Weitere Informationen finden Sie in den React-Dokumenten.

Gut zu wissen: Wenn action eine Funktion ist, werden die replace- und scroll-Props ignoriert.

Einschränkungen

• formAction: Kann in einem <button>- oder <input type="submit">-Feld verwendet werden, um die action-Prop zu überschreiben. Next.js führt eine clientseitige Navigation durch, aber dieser Ansatz unterstützt kein Prefetching.
  • Bei Verwendung von basePath muss dieser auch im formAction-Pfad enthalten sein, z.B. formAction="/base-path/search".
• key: Das Übergeben einer key-Prop an eine String-action wird nicht unterstützt. Wenn Sie ein erneutes Rendern auslösen oder eine Mutation durchführen möchten, sollten Sie stattdessen eine Funktions-action verwenden.

• onSubmit: Kann zur Handhabung der Formularübermittlungslogik verwendet werden. Der Aufruf von event.preventDefault() überschreibt jedoch das <Form>-Verhalten, z.B. die Navigation zur angegebenen URL.
• method, encType, target: Werden nicht unterstützt, da sie das <Form>-Verhalten überschreiben.
  • Ebenso können formMethod, formEncType und formTarget verwendet werden, um die method-, encType- bzw. target-Props zu überschreiben, und ihre Verwendung führt zum Standardverhalten des Browsers.
  • Wenn Sie diese Props benötigen, verwenden Sie stattdessen das HTML-<form>-Element.
• <input type="file">: Die Verwendung dieses Eingabetyps, wenn action ein String ist, entspricht dem Browserverhalten, indem der Dateiname anstelle des Dateiobjekts übermittelt wird.

Beispiele

Suchformular, das zu einer Suchergebnisseite führt

Sie können ein Suchformular erstellen, das zu einer Suchergebnisseite navigiert, indem Sie den Pfad als action übergeben:

import Form from 'next/form'

export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}

Wenn der Benutzer das Abfrage-Eingabefeld aktualisiert und das Formular übermittelt, werden die Formulardaten als Suchparameter in die URL kodiert, z.B. /search?query=abc.

Gut zu wissen: Wenn Sie einen leeren String "" an action übergeben, navigiert das Formular zur gleichen Route mit aktualisierten Suchparametern.

Auf der Ergebnisseite können Sie die Abfrage mit der searchParams-Prop von page.js abrufen und verwenden, um Daten aus einer externen Quelle abzurufen.

import { getSearchResults } from '@/lib/search'

export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const results = await getSearchResults((await searchParams).query)

  return <div>...</div>
}

Wenn die <Form> im sichtbaren Bereich des Benutzers erscheint, wird die gemeinsame UI (wie layout.js und loading.js) auf der /search-Seite vorab geladen. Bei Übermittlung navigiert das Formular sofort zur neuen Route und zeigt die Lade-UI an, während die Ergebnisse abgerufen werden. Sie können die Fallback-UI mit loading.js gestalten:

export default function Loading() {
  return <div>Loading...</div>
}

Um Fälle abzudecken, in denen die gemeinsame UI noch nicht geladen ist, können Sie dem Benutzer mit useFormStatus sofortiges Feedback geben.

Erstellen Sie zunächst eine Komponente, die einen Ladezustand anzeigt, wenn das Formular aussteht:

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

export default function SearchButton() {
  const status = useFormStatus()
  return (
    <button type="submit">{status.pending ? 'Suche läuft...' : 'Suchen'}</button>
  )
}

Aktualisieren Sie dann die Suchformularseite, um die SearchButton-Komponente zu verwenden:

import Form from 'next/form'
import { SearchButton } from '@/ui/search-button'

export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <SearchButton />
    </Form>
  )
}

Mutationen mit Server Actions

Sie können Mutationen durchführen, indem Sie eine Funktion an die action-Prop übergeben.

import Form from 'next/form'
import { createPost } from '@/posts/actions'

export default function Page() {
  return (
    <Form action={createPost}>
      <input name="title" />
      {/* ... */}
      <button type="submit">Beitrag erstellen</button>
    </Form>
  )
}

Nach einer Mutation ist es üblich, zur neuen Ressource umzuleiten. Sie können die redirect-Funktion von next/navigation verwenden, um zur neuen Beitragsseite zu navigieren.

Gut zu wissen: Da das "Ziel" der Formularübermittlung erst nach Ausführung der Aktion bekannt ist, kann <Form> die gemeinsame UI nicht automatisch vorab laden.

'use server'
import { redirect } from 'next/navigation'

export async function createPost(formData: FormData) {
  // Neuen Beitrag erstellen
  // ...

  // Zum neuen Beitrag umleiten
  redirect(`/posts/${data.id}`)
}

Dann können Sie auf der neuen Seite Daten mit der params-Prop abrufen:

import { getPost } from '@/posts/data'

export default async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const data = await getPost(id)

  return (
    <div>
      <h1>{data.title}</h1>
      {/* ... */}
    </div>
  )
}

Weitere Beispiele finden Sie in den Server Actions-Dokumenten.