How to Use useSearchParams in React for URL Query Parameters

In React, you use the useSearchParams hook from react-router-dom to read and update URL query parameters. It returns a stateful object for the current query parameters and a function to update them, letting your component react to URL changes easily.

Syntax

The useSearchParams hook is imported from react-router-dom. It returns an array with two items: the first is a URLSearchParams object representing the current query parameters, and the second is a function to update these parameters.

Basic usage:

• const [searchParams, setSearchParams] = useSearchParams();
• searchParams.get('key') reads a parameter value.
• setSearchParams({ key: 'value' }) updates the URL query string.

javascript

import { useSearchParams } from 'react-router-dom';

function MyComponent() {
  const [searchParams, setSearchParams] = useSearchParams();

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

  // Update query params
  const updateParam = () => {
    setSearchParams({ key: 'newValue' });
  };

  return null;
}

Example

This example shows a React component that reads a name query parameter from the URL and lets the user change it with a button. The URL updates automatically, and the displayed name changes accordingly.

javascript

import React from 'react';
import { useSearchParams } from 'react-router-dom';

export default function Greeting() {
  const [searchParams, setSearchParams] = useSearchParams();
  const name = searchParams.get('name') || 'Guest';

  const changeName = () => {
    setSearchParams({ name: 'Alice' });
  };

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

Output

Hello, Guest! [Button: Change Name to Alice]

When clicked, URL changes to ?name=Alice and text updates to "Hello, Alice!"

Common Pitfalls

• Not wrapping your app in a BrowserRouter: useSearchParams only works inside a React Router context.
• Replacing all query params unintentionally: Calling setSearchParams with a new object replaces all params. To keep existing ones, copy them first.
• Forgetting to handle null values: searchParams.get() returns null if the key is missing, so provide defaults.

javascript

/* Wrong: replaces all params, losing others */
setSearchParams({ page: '2' });

/* Right: keep existing params and add/update one */
const newParams = new URLSearchParams(searchParams);
newParams.set('page', '2');
setSearchParams(newParams);

Quick Reference

Action	Code Example	Description
Read param	searchParams.get('key')	Get value of 'key' from URL query
Set params	setSearchParams({ key: 'value' })	Replace all query params with new ones
Update one param	const p = new URLSearchParams(searchParams); p.set('key', 'value'); setSearchParams(p);	Add or update a single param without removing others
Remove param	const p = new URLSearchParams(searchParams); p.delete('key'); setSearchParams(p);	Remove a param from the URL query

Key Takeaways

useSearchParams returns current URL query params and a setter function to update them.

Always use useSearchParams inside a React Router context like BrowserRouter.

setSearchParams replaces all query params, so copy existing ones to update selectively.

searchParams.get returns null if the key is missing; handle defaults in your code.

Updating query params with useSearchParams updates the URL and triggers component re-render.