What is useSearchParams Hook in React Router

The useSearchParams hook is a built-in feature of React Router (version 6 and above) used to read and modify the query string in a utility URL. This article explains what the useSearchParams hook is, how it works under the hood, and provides practical examples of how to read and update query parameters in a React application.

Understanding useSearchParams

The useSearchParams hook is used to manage query parameters (the portion of the URL after the ? character, such as ?search=react&sort=asc). It mimics the behavior of React’s standard useState hook but persists the state directly in the URL instead of the component’s memory.

When you call useSearchParams, it returns an array containing two elements: 1. An instance of URLSearchParams: A read-only object representing the current query parameters. 2. An updater function: A function used to programmatically update the query parameters in the URL.

const [searchParams, setSearchParams] = useSearchParams();

Reading Query Parameters

To read the value of a specific query parameter, you use the .get() method provided by the URLSearchParams object.

For example, if your application URL is https://example.com/products?category=shoes&sort=price, you can extract these values using the following code:

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

function ProductList() {
  const [searchParams] = useSearchParams();
  
  const category = searchParams.get('category'); // Returns "shoes"
  const sort = searchParams.get('sort');         // Returns "price"

  return (
    <div>
      <p>Category: {category}</p>
      <p>Sorted by: {sort}</p>
    </div>
  );
}

If a query parameter does not exist in the URL, the .get() method will return null.

Updating Query Parameters

To update the query parameters in the URL, you call the updater function returned by the hook. This function accepts an object or a new URLSearchParams instance representing the new query parameters.

When called, the updater function modifies the URL search string and triggers a component re-render.

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

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

  const handleFilterChange = (newCategory) => {
    // This updates the URL to: ?category=newCategoryValue
    setSearchParams({ category: newCategory });
  };

  return (
    <div>
      <button onClick={() => handleFilterChange('electronics')}>Electronics</button>
      <button onClick={() => handleFilterChange('clothing')}>Clothing</button>
    </div>
  );
}

Preserving Existing Parameters

By default, passing an object to the updater function overrides the entire query string. If you want to update one parameter while preserving others, you must copy the existing parameters first.

You can achieve this by using the URLSearchParams constructor or by iterating over the existing parameters:

const updateSortParam = (newSortValue) => {
  const currentParams = Object.fromEntries([...searchParams]);
  setSearchParams({
    ...currentParams,
    sort: newSortValue
  });
};

Common Use Cases

The useSearchParams hook is widely used in web applications for features that benefit from URL-driven state, such as: