How to Use useSearchParams in Next.js for URL Query Handling

In Next.js, you can use the useSearchParams hook from the next/navigation module to read URL query parameters in client components. It returns a URLSearchParams object to get query values. To update query parameters, use the useRouter hook's push or replace methods, as useSearchParams does not provide a setter function.

Syntax

The useSearchParams hook is imported from next/navigation. It returns a URLSearchParams object to read query parameters.

Example syntax:

const searchParams = useSearchParams();

- searchParams: lets you get query values like searchParams.get('key').

To update query parameters, use the useRouter hook's push or replace methods.

javascript

import { useSearchParams, useRouter } from 'next/navigation';

export default function Component() {
  const searchParams = useSearchParams();
  const router = useRouter();

  // Read a query param
  const value = searchParams.get('key');

  // Update query params
  function updateQuery() {
    const newParams = new URLSearchParams(searchParams);
    newParams.set('key', 'newValue');
    router.push(`?${newParams.toString()}`);
  }

  return null;
}

Example

This example shows a Next.js client component that reads a name query parameter from the URL and updates it when a button is clicked. The displayed greeting updates automatically based on the URL query.

javascript

"use client";

import { useSearchParams, useRouter } from 'next/navigation';

export default function Greeting() {
  const searchParams = useSearchParams();
  const router = useRouter();
  const name = searchParams.get('name') || 'Guest';

  function changeName() {
    const newParams = new URLSearchParams(searchParams);
    newParams.set('name', 'Alice');
    router.push(`?${newParams.toString()}`);
  }

  return (
    <div>
      <p>Hello, {name}!</p>
      <button onClick={changeName}>Change Name to Alice</button>
    </div>
  );
}

Output

Hello, Guest! (initially)
After clicking button: Hello, Alice!

Common Pitfalls

• Not using a client component: useSearchParams only works in client components. Forgetting "use client"; at the top causes errors.
• Mutating URLSearchParams directly: Always create a new URLSearchParams instance when updating query parameters. Modifying the existing object won't update the URL.
• Ignoring reactivity: The component re-renders when query params change, so use searchParams.get() inside the component body, not outside.

javascript

/* Wrong: Mutating existing searchParams */
function wrongUpdate() {
  searchParams.set('name', 'Bob');
  // This won't update the URL
}

/* Right: Create new URLSearchParams and use router.push */
function rightUpdate() {
  const newParams = new URLSearchParams(searchParams);
  newParams.set('name', 'Bob');
  router.push(`?${newParams.toString()}`); // Correct update
}

Quick Reference

Summary tips for using useSearchParams in Next.js:

• Import from next/navigation.
• Use only in client components ("use client"; required).
• Read query params with searchParams.get('key').
• Update query params by using useRouter and calling push or replace with updated query strings.
• Component re-renders automatically on query param changes.

Key Takeaways

Use useSearchParams only inside client components with "use client" directive.

Read query parameters with searchParams.get('paramName').

Update URL queries by using useRouter's push or replace methods with new query strings.

Do not mutate the existing URLSearchParams object directly; always create a new one.

Components re-render automatically when search parameters change.