useSearch

React hook that returns the parsed URL search parameters as a typed object, along with a setter function to update them. The framework automatically provides the router context — no manual setup required.

Import

import { useSearch } from "catmint/hooks";

Signature

function useSearch<
  T extends Record<string, string | undefined> = Record<
    string,
    string | undefined
  >,
>(): [T, (params: T) => void];

Type Parameters

Parameter	Default	Description
`T`	`Record<string, string \| undefined>`	The expected shape of the search parameters

Parameters

This hook takes no parameters.

Return Value

Returns a tuple [params, setParams]:

Index	Type	Description
`0`	`T`	Current search parameters as a typed object
`1`	`(params: T) => void`	Function to update the search parameters

Errors

Throws if the router context is missing (this should not happen in normal usage — the framework injects it automatically).

Examples

import { useSearch } from "catmint/hooks";

function ProductList() {
  const [{ sort, page }, setSearch] = useSearch<{
    sort?: string;
    page?: string;
  }>();

  return (
    <div>
      <p>
        Sort: {sort ?? "default"}, Page: {page ?? "1"}
      </p>
      <button onClick={() => setSearch({ sort: "price", page: "1" })}>
        Sort by price
      </button>
    </div>
  );
}

// Updating a single parameter while preserving others
function Pagination() {
  const [search, setSearch] = useSearch<{ page?: string; q?: string }>();

  const nextPage = () => {
    const current = parseInt(search.page ?? "1", 10);
    setSearch({ ...search, page: String(current + 1) });
  };

  return <button onClick={nextPage}>Next page</button>;
}