[Next.js 15] App Router 와 next/form : URL query string 자동 업데이트 (feat. 검색기능 구현)

 

최근 Next.js 15 버전을 공부하고 있는데

next/form 을 사용해서 URL query string 자동 업데이트를 하는 기능이

유용할 것 같아 정리해보려고 한다.

 

검색 기능을 구현하는 예시를 통해 어떤 식으로 활용하면 좋을지도 정리했다

 

React 나 Next.js Pages Router 에서 URL query string 을 다루는 방법은

이전 게시글에 정리해두었으니 참고하면 된다.

[React] 새 창에서 동일한 세팅 값 유지하도록 하기 (URL query string 활용)

 

---

 

목차

• server component에서 URL query string 가져오기
• URL query string을 활용해 검색 기능 구현하기 (next/form)

 

📌 server component에서 URL query string 가져오기

app/(root)/page.tsx

export default async function Home({
    searchParams,
}: {
    searchParams?: Promise<{ query?: string }>
}) {
    const query = (await searchParams)?.query

    return (
        <SearchForm query={query} />
    )
}

• Next.js의 App router 는 기본적으로 server component다.
• 이때, URL 의 query string 은 컴포넌트의 파라미터로 바로 전달되므로 별도의 훅이나 상태 관리 없이 사용할 수 있다.
• URL 의 query 파라미터가 searchParams 라는 프로퍼티로 전달되어, server side 에서 바로 사용 가능하다.
• 즉, searchParams.query 로 URL query string 을 가져다 쓸 수 있다.

 

📌 URL query string을 활용해 검색 기능 구현하기 (next/form)

components/SearchForm.tsx

import React from 'react'
import SearchFormReset from '@/components/SearchFormReset'
import Form from 'next/form'
import { Search } from 'lucide-react'

const SearchForm = ({ query }: { query?: string }) => {
    return (
        <Form action="/" scroll={false} className="search-form">
            <input
                name="query"
                defaultValue={query}
                className="search-input"
                placeholder="Search Startups"
            />
            <div className="flex gap-2">
                {query && <SearchFormReset />}
                <button type="submit" className="search-btn text-white">
                    <Search className="size-5" />
                </button>
            </div>
        </Form>
    )
}

export default SearchForm

• next/form : <Form>은 폼 데이터를 server actions와 연동하거나, 폼 제출 후 페이지 전환 등의 부드러운 동작을 지원하는 최신 기능들을 포함한다.
• action="/" : 폼 제출 시 데이터를 보낼 URL 이다.
• scroll={false} : 폼 제출 후 페이지가 자동으로 최상단으로 이동되는 기본 동작을 막는다.
• 폼이 제출될 때, 브라우저는 폼 안의 입력값을 해당 input의 name 속성을 키로 하여 전송하게 된다.
  이 경우 action="/"로 지정되어 있으므로, 입력된 검색어는 URL에 ?query=입력값 형태로 자동으로 추가된다.

 

components/SearchFormReset.tsx

'use client'

import React from 'react'
import Link from 'next/link'
import { X } from 'lucide-react'

export default function SearchFormReset() {
    const reset = () => {
        const form = document.querySelector('.search-form') as HTMLFormElement

        if (form) form.reset()
    }

    return (
        <button type="reset" onClick={reset}>
            <Link href="/" className="search-btn text-white">
                <X className="size-5" />
            </Link>
        </button>
    )
}

• 'use client' : 검색어를 초기화하는 click event 가 적용되어야 하므로 client component로 변경한다.
• type="reset" 버튼 : 입력 필드의 값을 초기값으로 돌려놓는다.
• 버튼 클릭 시, 폼을 리셋하고, 내부의 <Link>를 통해 / 로 이동한다.