Skip to content
ToapiToapi

useSearchParams

The useSearchParams hook provides access to the current URL search parameters (query string). It returns an ImmutableSearchParams instance that extends the standard URLSearchParams with immutable mutation methods.

Usage

Section titled “Usage”

It’s really just URLSearchParams, but the mutating methods return a new instance instead of modifying the current one. This makes it safe to derive an updated query string for a Link or useRouter call without accidentally mutating shared state.

To change one search parameter while preserving the rest:

import { Link, useSearchParams } from "@toapi/router";


function Example() {
  const searchParams = useSearchParams();


  return <Link href={"?" + searchParams.set("query", "whatever")} />;
}

To delete a parameter:

const searchParams = useSearchParams();


return <Link href={"?" + searchParams.delete("query")} />;

For array parameters (append rather than replace):

const searchParams = useSearchParams();


return <Link href={"?" + searchParams.append("options[]", "value")} />;

Return Value

Section titled “Return Value”
  • Type: ImmutableSearchParams (a subclass of URLSearchParams)

All the read methods of URLSearchParams work as usual — get, getAll, has, keys, values, entries, forEach, toString, and size.

Immutable mutators

Section titled “Immutable mutators”

Unlike URLSearchParams, these methods do not modify the instance. They each return a new ImmutableSearchParams with the change applied:

Method Behavior
set(key, value) Returns a new instance with key set to value.
append(name, value) Returns a new instance with value appended under name.
delete(key) Returns a new instance with key removed.

Because they return a new instance, calls can be chained:

const searchParams = useSearchParams();
const next = searchParams.set("category", "electronics").set("sort", "price");

The search getter

Section titled “The search getter”

ImmutableSearchParams adds a search getter that returns the query string including the leading ?, or an empty string when there are no parameters:

const searchParams = useSearchParams();
searchParams.search; // "?category=electronics&sort=price" — or "" when empty
Section titled “Related”