Suggest an edit

Improve this article

Refine the answer for “What does useSearchParams() do?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## What `useSearchParams()` does

> `useSearchParams()` lets you:
>
> 1. read parameters from the URL (`?page=2&sort=asc`)
> 2. change them (for example, `setSearchParams({ page: 3 })`)
> 3. update the query string without reloading the page

---

## A basic usage example

```javascript
import { useSearchParams } from "react-router-dom";

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

const page = searchParams.get("page") || 1;
  const sort = searchParams.get("sort") || "asc";

return (
    <div>
      <p>Current page: {page}</p>
      <p>Sort: {sort}</p>

<button onClick={() => setSearchParams({ page: 2, sort: "desc" })}>
        Change parameters
      </button>
    </div>
  );
}
```

If the URL =

```javascript
https://example.com/products?page=1&sort=asc
```

`searchParams.get("page")` → `"1"`
`searchParams.get("sort")` → `"asc"`

Clicking the button changes the URL to:

```javascript
https://example.com/products?page=2&sort=desc
```

Without reloading the page.

---

## What `useSearchParams()` returns

The hook returns an **array of two elements**:

```javascript
const [searchParams, setSearchParams] = useSearchParams();
```

| Element | Type | Purpose |
| --- | --- | --- |
| `searchParams` | `URLSearchParams` | Lets you read parameters (`get`, `has`, `entries`, etc.) |
| `setSearchParams` | `(params) => void` | Lets you update the query string |

---

## Methods on the `searchParams` object

| Method | Description | Example |
| --- | --- | --- |
| `.get(name)` | Returns the parameter's value | `searchParams.get("page")` |
| `.getAll(name)` | Returns an array of all values for the parameter | `searchParams.getAll("tag")` |
| `.has(name)` | Checks whether the parameter exists | `searchParams.has("sort")` |
| `.entries()` | An iterator over all key-value pairs | `for (const [k,v] of searchParams.entries())` |
| `.toString()` | Returns the query string | `page=2&sort=asc` |

---

## An example of reading parameters

```javascript
function Blog() {
  const [searchParams] = useSearchParams();

const category = searchParams.get("category");
  const tag = searchParams.get("tag");

return (
    <h2>
      Category: {category}, Tag: {tag}
    </h2>
  );
}
```

URL:

```javascript
/blog?category=react&tag=hooks
```

Renders:

```javascript
Category: react, Tag: hooks
```

---

## An example of changing parameters

```javascript
const [searchParams, setSearchParams] = useSearchParams();

function handleNextPage() {
  const nextPage = Number(searchParams.get("page") || 1) + 1;
  setSearchParams({ page: nextPage });
}
```

Calling `handleNextPage()` changes the URL:

```javascript
?page=1  →  ?page=2
```

The page does not reload, React Router just updates the address bar.

---

## An example of combining it with state

```javascript
const [searchParams, setSearchParams] = useSearchParams();
const [filter, setFilter] = useState(searchParams.get("filter") || "");

useEffect(() => {
  setSearchParams({ filter });
}, [filter]);
```

Now changing the `filter` state gets synchronized with the URL.

---

## Why this is needed

| Task | Why `useSearchParams()` fits perfectly |
| --- | --- |
| Filters and sorting | You can persist the selected filters in the URL |
| Pagination | The current page is stored as `?page=2` |
| Sharing links | You can copy a link with parameters and share it |
| Syncing with state | React state ↔ URL |
| Navigation without reloading | We change parameters but stay on the same page |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts489 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.