Form

<Form> コンポーネントはHTMLの<form>要素を拡張し、プリフェッチとローディングUI、送信時のクライアントサイドナビゲーション、およびプログレッシブエンハンスメントを提供します。

URL検索パラメータを更新するフォームに便利で、上記を実現するために必要な定型コードを削減できます。

基本的な使用法:

import Form from 'next/form'

export default function Page() {
  return (
    <Form action="/search">
      {/* 送信時、入力値がURLに追加されます
          例: /search?query=abc */}
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}

リファレンス

<Form>コンポーネントの動作は、actionプロパティにstringまたはfunctionのどちらを渡すかによって異なります。

• actionが文字列の場合、<Form>は**GET**メソッドを使用するネイティブHTMLフォームのように動作します。フォームデータは検索パラメータとしてURLにエンコードされ、フォームが送信されると指定されたURLにナビゲートします。さらにNext.jsは:
  • フォームが表示されるときにパスをプリフェッチし、共有UI（例: layout.jsやloading.js）をプリロードしてナビゲーションを高速化します。
  • フォーム送信時にクライアントサイドナビゲーションを実行し、ページ全体のリロードを防ぎます。これにより共有UIとクライアントサイドの状態が保持されます。
• actionが関数（サーバーアクション）の場合、<Form>はReactフォームのように動作し、フォーム送信時にアクションを実行します。

action (文字列) プロパティ

actionが文字列の場合、<Form>コンポーネントは以下のプロパティをサポートします:

• action: フォーム送信時にナビゲートするURLまたはパス。
  • 空文字列""を指定すると、同じルートに検索パラメータを更新してナビゲートします。
• replace: ブラウザの履歴スタックに新しい状態をプッシュする代わりに、現在の履歴状態を置き換えます。デフォルトはfalse。
• scroll: ナビゲーション時のスクロール動作を制御します。デフォルトはtrueで、新しいルートのトップにスクロールし、前後のナビゲーションでスクロール位置を維持します。
• prefetch: フォームがユーザーのビューポートに表示されたときにパスをプリフェッチするかどうかを制御します。デフォルトはtrue。

action (関数) プロパティ

actionが関数の場合、<Form>コンポーネントは以下のプロパティをサポートします:

• action: フォーム送信時に呼び出されるサーバーアクション。詳細はReactドキュメントを参照してください。

知っておくと便利: actionが関数の場合、replaceとscrollプロパティは無視されます。

注意点

• formAction: <button>または<input type="submit">フィールドで使用してactionプロパティを上書きできます。Next.jsはクライアントサイドナビゲーションを実行しますが、この方法ではプリフェッチはサポートされません。
  • basePathを使用する場合、formActionパスにも含める必要があります。例: formAction="/base-path/search"。
• key: 文字列actionにkeyプロパティを渡すことはサポートされていません。再レンダリングをトリガーしたり、ミューテーションを実行したりしたい場合は、代わりに関数actionの使用を検討してください。

• onSubmit: フォーム送信ロジックを処理するために使用できます。ただし、event.preventDefault()を呼び出すと、指定されたURLへのナビゲーションなど<Form>の動作が上書きされます。
• method, encType, target: これらは<Form>の動作を上書きするためサポートされていません。
  • 同様に、formMethod、formEncType、formTargetはそれぞれmethod、encType、targetプロパティを上書きするために使用できますが、これらを使用するとネイティブのブラウザ動作にフォールバックします。
  • これらのプロパティを使用する必要がある場合は、代わりにHTMLの<form>要素を使用してください。
• <input type="file">: actionが文字列の場合、この入力タイプを使用すると、ファイルオブジェクトではなくファイル名を送信するというブラウザの動作に従います。

例

検索結果ページに移動する検索フォーム

actionにパスを渡すことで、検索結果ページにナビゲートする検索フォームを作成できます:

import Form from 'next/form'

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

ユーザーがクエリ入力フィールドを更新してフォームを送信すると、フォームデータは検索パラメータとしてURLにエンコードされます（例: /search?query=abc）。

知っておくと便利: actionに空文字列""を渡すと、フォームは同じルートに検索パラメータを更新してナビゲートします。

結果ページでは、searchParams page.jsプロパティを使用してクエリにアクセスし、外部ソースからデータを取得するために使用できます。

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>
}

<Form>がユーザーのビューポートに表示されると、/searchページの共有UI（layout.jsやloading.jsなど）がプリフェッチされます。送信時、フォームはすぐに新しいルートにナビゲートし、結果が取得されている間はローディングUIを表示します。loading.jsを使用してフォールバックUIを設計できます:

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

共有UIがまだロードされていない場合に備えて、useFormStatusを使用してユーザーに即時フィードバックを表示できます。

まず、フォームが保留中の場合にローディング状態を表示するコンポーネントを作成します:

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

export default function SearchButton() {
  const status = useFormStatus()
  return (
    <button type="submit">{status.pending ? '検索中...' : '検索'}</button>
  )
}

次に、検索フォームページを更新してSearchButtonコンポーネントを使用します:

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

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

サーバーアクションによるミューテーション

actionプロパティに関数を渡すことでミューテーションを実行できます。

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

export default function Page() {
  return (
    <Form action={createPost}>
      <input name="title" />
      {/* ... */}
      <button type="submit">投稿を作成</button>
    </Form>
  )
}

ミューテーション後、新しいリソースにリダイレクトするのが一般的です。next/navigationのredirect関数を使用して、新しい投稿ページにナビゲートできます。

知っておくと便利: フォーム送信の「宛先」はアクションが実行されるまでわからないため、<Form>は共有UIを自動的にプリフェッチできません。

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

export async function createPost(formData: FormData) {
  // 新しい投稿を作成
  // ...

  // 新しい投稿にリダイレクト
  redirect(`/posts/${data.id}`)
}

新しいページでは、paramsプロパティを使用してデータを取得できます:

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>
  )
}

その他の例についてはサーバーアクションのドキュメントを参照してください。