useReadonlySearchParams

useReadonlySearchParams provides a convenient way to read the window.location.search as a URLSearchParams object and keep it up-to-date when the URL changes.

Do notice that the returned URLSearchParams object is read-only. If you want to modify the search params, perform client-side navigation via a routing library (like React Router), a framework (like Next.js), or the browser History API.

Usage

import { useReadonlySearchParams, ReadonlyURLSearchParams } from 'foxact/use-readonly-search-params';
 
const readOnlySearchParams = useReadonlySearchParams();
 
console.log(readOnlySearchParams instanceof ReadonlyURLSearchParams); // true

History API Provider

By default, useReadonlySearchParams subscribes only to the browser’s popstate event. This keeps it up-to-date during history traversal, such as when the user navigates back or forward. Calling window.history.pushState or window.history.replaceState does not emit popstate and therefore does not update the hook by default.

To observe calls to window.history.pushState and window.history.replaceState, wrap your component tree with the ReadonlySearchParamsProvider:

import {
  ReadonlySearchParamsProvider,
  useReadonlySearchParams
} from 'foxact/use-readonly-search-params';
 
function SearchParamsReader() {
  const searchParams = useReadonlySearchParams();
  return searchParams.get('query');
}
 
function App() {
  return (
    <ReadonlySearchParamsProvider>
      <SearchParamsReader />
    </ReadonlySearchParamsProvider>
  );
}

The provider patches both History API methods when it mounts and restores them during its React effect cleanup.

development builds throw if multiple independent providers are detected. Only descendant hooks opt into these additional updates; hooks outside the provider keep the default popstate-only behavior.

Server-side Rendering

useReadonlySearchParams accepts an optional parameter getServerDefaultValue, which is a function that returns a URLSearchParams or ReadonlyURLSearchParams object to be used as the initial value on the server.

When getServerDefaultValue is omitted (which is the default behavior), React will find the closest <Suspense> boundary and render its fallback UI into the generated server HTML on the server. The user will see the fallback UI at first. React will attempt to render the component during the hydration on the browser, where the latest URLSearchParams is generated from the browser’s window.location.search and the user will see the actual value after the hydration is finished. See also <Suspense> Providing a fallback for server errors and client-only content  at React docs.

If you provide the getServerDefaultValue, React will use the initial value to render the UI and generate HTML on the server. The user will see the initial value (which might be stale) first. On the client, React will first use the initial value to hydrate the server-side rendered HTML, and then immediately re-render the component with the actual value (read from the browser’s window.location.search) after the hydration. The user will see the latest value after both the hydration and the re-render.

import { useReadonlySearchParams, ReadonlyURLSearchParams } from 'foxact/use-window-location-url-search-params';
 
const emptySearchParams = new ReadonlyURLSearchParams();
 
useReadonlySearchParams(() => emptySearchParams /* getServerDefaultValue - an empty URLSearchParams */);