[Next.js] Next.js 15의 새로운 Form 컴포넌트 가이드

 

기존 form 과의 주요 차이점 

 

로딩 UI의 프리페칭 가능 ( 화면 미리 불러오기 )
form 제출 시 부드럽게 페이지 전환 (깜빡임 없음) : 클라이언트 사이드 네비게이션

preventDefault()  기본 수행

쿼리 파라미터 를 name 속성에 맞춰 자동으로 붙여줌

 

 

기본 작성법

import Form from 'next/form'

function SearchForm() {
  return (
    <Form action="/search">
      <input 
        name="query" 
        placeholder="검색어를 입력하세요"
      />
      <button type="submit">검색</button>
    </Form>
  )
}

 

input name='query' 은 자동으로 쿼리 파라미터를 붙이는 기능입니다.

url이 이렇게 됩니다 ......./search?query='인풋에서 쓴 내용'

 

---

 

 

<Form> 컴포넌트의 동작은 액션 프로퍼티가 문자열인지 함수인지에 따라 달라집니다.

 

1.  액션이 문자열인 경우 <Form>은 GET 메서드를 사용하는 기본 HTML 양식처럼 동작합니다.

양식 데이터는 검색 매개변수로 URL에 인코딩되며, 양식이 제출되면 지정된 URL로 이동합니다.

 

• 또한 Next.js: 양식이 표시될 때 경로를 미리 가져와 공유 UI(예: layout.js 및 loading.js)를
  미리 로드하여 탐색 속도를 높입니다.
• 양식이 제출되면 전체 페이지를 다시 로드하는 대신 깜빡임 없는 부드럽게 페이지 전환 ( client-side navigation )
  을 하게 되며 공유 UI와 클라이언트 측 상태가 유지됩니다.

 

2.  액션이 함수(서버 액션)인 경우, <Form>은 폼이 제출될 때 액션을 실행하는 React 폼처럼 작동합니다.

 

 

 

 

action (string) Props

Prop	부가설명	Example	Type	Required
action	''  공란이면 지금화면 그대로	action="/search"	string (URL or relative path)	Yes
replace	router puah 냐 replace 냐	replace={false}	boolean	-
scroll	화면 전환시 기존 스크롤 위치고정 여부	scroll={true}	boolean	-
prefetch	ui 프리패치 여부	prefetch={true}	boolean	-

 

 

action (function) Props

Prop	Example	Type	Required
action	action={myAction}	function (Server Action)	Yes

 

액션이 함수인 경우 replace및 scroll props는 무시됩니다.

 

 

주의사항

 

1. formAction

// 예시 2: 게시글 작성 폼
<Form action="/posts/save">
  <input name="title" />
  <textarea name="content" />
  
  {/* 임시저장 */}
  <button type="submit" formAction="/posts/draft">
    임시저장
  </button>
  
  {/* 저장하기 */}
  <button type="submit">
    저장하기
  </button>
</Form>

 

• <button> 또는 <input type="submit"> 에서 사용 가능
• Form의 기본 action 속성을 개별적으로 덮어쓸 수 있음
• 클라이언트 사이드 네비게이션은 지원하지만, 프리페칭(미리 데이터 가져오기)은 지원하지 않음
• basePath를 사용할 경우 반드시 포함해야 함 (예: formAction="/base-path/search")

 

 

2. key

// ❌ 지원하지 않는 방식
<Form action="/search" key={searchId}>

// ✅ 대신 함수 action 사용 권장
<Form action={async () => {
  // 여기서 원하는 작업 수행
}}>

 

문자열 action에서는 key prop 지원하지 않음
재렌더링이나 데이터 변경이 필요한 경우 함수 action 사용 권장

 

 

3. onSubmit

// ⚠️ 주의: preventDefault() 사용 시
<Form 
  action="/search"
  onSubmit={(e) => {
    e.preventDefault() // Form의 클라이언트 사이드 네비게이션 기능이 작동하지 않게 됨
    // ...
  }}
>

 

폼 제출 시 로직을 추가할 수 있음
하지만 preventDefault()를 사용하면 Form 컴포넌트의 기본 네비게이션 기능이 작동하지 않으니 주의

( 페이지 전환이 발생하지 않음)

4. 지원하지 않는 속성들

// ❌ 지원하지 않는 속성들
<Form 
  method="POST"      // 지원 안됨
  encType="..."      // 지원 안됨
  target="_blank"    // 지원 안됨
>

// ✅ 이런 기능이 필요하다면 일반 HTML form 사용
<form method="POST" target="_blank">

 

 

5. 파일 입력

<Form action="/upload">
  <input type="file" name="document" />
  {/* 
    문자열 action 사용 시 파일 객체가 아닌 
    파일 이름만 전송됨
  */}
</Form>

 

공식 문서를 토대로 작성했습니다.

https://nextjs.org/docs/app/api-reference/components/form

Components: <Form> | Next.js