Form
<Form>
コンポーネントは、HTML <form>
要素を拡張し、プリフェッチ、ローディングUI、クライアント側のナビゲーション、プログレッシブエンハンスメントを提供します。
URLのsearchパラメータを更新するフォームに役立ち、これらを実現するために必要な定型コードを削減します。
基本的な使用方法:
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
プロップが文字列か関数かによって異なります。
action
が文字列の場合、<Form>
はGET
メソッドを使用するネイティブHTMLフォームのように動作します。フォームデータはsearchパラメータとしてURLにエンコードされ、フォーム送信時に指定されたURLにナビゲーションします。さらに、Next.jsは以下を行います:- フォームが表示されるとプリフェッチし、共有UI(例:
layout.js
とloading.js
)をプリロードし、より高速なナビゲーションを実現します。 - フォーム送信時に、フルページリロードではなくクライアント側のナビゲーションを実行します。これにより、共有UIとクライアント側の状態が保持されます。
- フォームが表示されるとプリフェッチし、共有UI(例:
action
が関数(サーバーアクション)の場合、<Form>
はReactフォームのように動作し、フォーム送信時にアクションを実行します。
action
(文字列)Props
action
が文字列の場合、<Form>
コンポーネントは以下のPropsをサポートします:
Prop | 例 | 型 | 必須 |
---|---|---|---|
action | action="/search" | string (URLまたは相対パス) | はい |
replace | replace={false} | boolean | - |
scroll | scroll={true} | boolean | - |
prefetch | prefetch={true} | boolean | - |
action
:フォーム送信時にナビゲーションするURL またはパス。- 空の文字列
""
は、更新されたsearchパラメータで同じルートにナビゲーションします。
- 空の文字列
replace
:ブラウザの履歴スタックに新しい履歴状態をプッシュする代わりに、現在の履歴状態を置き換えます。デフォルトはfalse
です。scroll
:ナビゲーション時のスクロール動作を制御します。デフォルトはtrue
で、新しいルートの先頭にスクロールし、前後のナビゲーションのスクロール位置を維持します。prefetch
:フォームがユーザーのビューポートに表示されたときに、パスをプリフェッチするかどうかを制御します。デフォルトはtrue
です。
action
(関数)Props
action
が関数の場合、<Form>
コンポーネントは以下のPropをサポートします:
Prop | 例 | 型 | 必須 |
---|---|---|---|
action | action={myAction} | function (サーバーアクション) | はい |
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">送信</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>読み込み中...</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 data = await getPost((await params).id)
return (
<div>
<h1>{data.title}</h1>
{/* ... */}
</div>
)
}
より多くの例については、サーバーアクションのドキュメントを参照してください。