Form Component

The<Form> component extends the HTML<form> element to provideprefetching ofloading UI,client-side navigation on submission, andprogressive enhancement.

It's useful for forms that update URL search params as it reduces the boilerplate code needed to achieve the above.

Basic usage:

import Formfrom'next/form'exportdefaultfunctionPage() {return (    <Formaction="/search">      {/* On submission, the input value will beappended to          the URL, e.g. /search?query=abc */}      <inputname="query" />      <buttontype="submit">Submit</button>    </Form>  )}

Reference

The behavior of the<Form> component depends on whether theaction prop is passed astring orfunction.

• Whenaction is astring, the<Form> behaves like a native HTML form that uses aGET method. The form data is encoded into the URL as search params, and when the form is submitted, it navigates to the specified URL. In addition, Next.js:
  • Prefetches the path when the form becomes visible, this preloads shared UI (e.g.layout.js andloading.js), resulting in faster navigation.
  • Performs aclient-side navigation instead of a full page reload when the form is submitted. This retains shared UI and client-side state.
• Whenaction is afunction (Server Action),<Form> behaves like aReact form, executing the action when the form is submitted.

action (string) Props

Whenaction is a string, the<Form> component supports the following props:

• action: The URL or path to navigate to when the form is submitted.
  • An empty string"" will navigate to the same route with updated search params.
• replace: Replaces the current history state instead of pushing a new one to thebrowser's history stack. Default isfalse.
• scroll: Controls the scroll behavior during navigation. Defaults totrue, this means it will scroll to the top of the new route, and maintain the scroll position for backwards and forwards navigation.
• prefetch: Controls whether the path should be prefetched when the form becomes visible in the user's viewport. Defaults totrue.

action (function) Props

Whenaction is a function, the<Form> component supports the following prop:

• action: The Server Action to be called when the form is submitted. See theReact docs for more.

Good to know: Whenaction is a function, thereplace andscroll props are ignored.

Caveats

• formAction: Can be used in a<button> or<input type="submit"> fields to override theaction prop. Next.js will perform a client-side navigation, however, this approach doesn't support prefetching.
  • When usingbasePath, you must also include it in theformAction path. e.g.formAction="/base-path/search".
• key: Passing akey prop to a stringaction is not supported. If you'd like to trigger a re-render or perform a mutation, consider using a functionaction instead.

• onSubmit: Can be used to handle form submission logic. However, callingevent.preventDefault() will override<Form> behavior such as navigating to the specified URL.
• method,encType,target: Are not supported as they override<Form> behavior.
  • Similarly,formMethod,formEncType, andformTarget can be used to override themethod,encType, andtarget props respectively, and using them will fallback to native browser behavior.
  • If you need to use these props, use the HTML<form> element instead.
• <input type="file">: Using this input type when theaction is a string will match browser behavior by submitting the filename instead of the file object.

Examples

Search form that leads to a search result page

You can create a search form that navigates to a search results page by passing the path as anaction:

import Formfrom'next/form'exportdefaultfunctionPage() {return (    <Formaction="/search">      <inputname="query" />      <buttontype="submit">Submit</button>    </Form>  )}

When the user updates the query input field and submits the form, the form data will be encoded into the URL as search params, e.g./search?query=abc.

Good to know: If you pass an empty string"" toaction, the form will navigate to the same route with updated search params.

On the results page, you can access the query using thesearchParamspage.js prop and use it to fetch data from an external source.

import { getSearchResults }from'@/lib/search'exportdefaultasyncfunctionSearchPage({  searchParams,}: {  searchParams:Promise<{ [key:string]:string|string[]|undefined }>}) {constresults=awaitgetSearchResults((await searchParams).query)return <div>...</div>}

When the<Form> becomes visible in the user's viewport, shared UI (such aslayout.js andloading.js) on the/search page will be prefetched. On submission, the form will immediately navigate to the new route and show loading UI while the results are being fetched. You can design the fallback UI usingloading.js:

exportdefaultfunctionLoading() {return <div>Loading...</div>}

To cover cases when shared UI hasn't yet loaded, you can show instant feedback to the user usinguseFormStatus.

First, create a component that displays a loading state when the form is pending:

'use client'import { useFormStatus }from'react-dom'exportdefaultfunctionSearchButton() {conststatus=useFormStatus()return (    <buttontype="submit">{status.pending?'Searching...':'Search'}</button>  )}

Then, update the search form page to use theSearchButton component:

import Formfrom'next/form'import { SearchButton }from'@/ui/search-button'exportdefaultfunctionPage() {return (    <Formaction="/search">      <inputname="query" />      <SearchButton />    </Form>  )}

Mutations with Server Actions

You can perform mutations by passing a function to theaction prop.

import Formfrom'next/form'import { createPost }from'@/posts/actions'exportdefaultfunctionPage() {return (    <Formaction={createPost}>      <inputname="title" />      {/* ... */}      <buttontype="submit">Create Post</button>    </Form>  )}

After a mutation, it's common to redirect to the new resource. You can use theredirect function fromnext/navigation to navigate to the new post page.

Good to know: Since the "destination" of the form submission is not known until the action is executed,<Form> cannot automatically prefetch shared UI.

'use server'import { redirect }from'next/navigation'exportasyncfunctioncreatePost(formData:FormData) {// Create a new post// ...// Redirect to the new postredirect(`/posts/${data.id}`)}

Then, in the new page, you can fetch data using theparams prop:

import { getPost }from'@/posts/data'exportdefaultasyncfunctionPostPage({  params,}: {  params:Promise<{ id:string }>}) {const {id }=await paramsconstdata=awaitgetPost(id)return (    <div>      <h1>{data.title}</h1>      {/* ... */}    </div>  )}

See theServer Actions docs for more examples.