The useSearchParams Hook for URL Queries

WHY IT EXISTS Web apps often store state in the URL's query string, like ?page=2&sort=asc. Manually parsing this from the browser's location object is clumsy and not reactive. The useSearchParams hook provides a clean, Next.js-native way to read these values inside your components and automatically re-render when they change.

THE MENTAL MODEL Think of useSearchParams as a read-only subscription to the URL's query string. It gives you an object that represents the current parameters. When the URL changes, Next.js gives you a new version of this object, triggering a re-render in your component with the updated data. You don't read the URL; you subscribe to its state.

HOW IT WORKS First, mark your component with 'use client' at the top of the file. Then, import the hook from next/navigation. Calling const searchParams = useSearchParams() inside your component gives you a read-only URLSearchParams object. You can then use its methods, like searchParams.get('sort') to retrieve a value, or searchParams.has('page') to check if a parameter exists. Any change to the URL's query string will cause your component to re-render.

WHEN TO USE IT Use this hook whenever a Client Component's rendering logic depends on URL query parameters. This is common for building search result pages that reflect the search term, filtering and sorting controls for a list of items, or handling pagination where the page number is stored in the URL.

WHEN NOT TO USE IT The most common mistake is using this hook in a Next.js Server Component. It is a client-side hook and will cause an error. To access search parameters in a Server Component (like a page.js file), use the searchParams prop that is automatically passed to the page. Also, do not use this hook if you need to modify the URL; for that, you need to use the useRouter hook or the <Link> component to navigate to a new URL with updated parameters.

ONE CANONICAL EXAMPLE Here is a simple component that displays a search query from the URL. If the URL is /search?q=react, it will display "Searching for: react".

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchLabel() { const searchParams = useSearchParams() const query = searchParams.get('q')

return Searching for: {query} }