Skip to main content

useSyncedSearchParams

Bidirectionally syncs component state with URL search parameters. Reading is immediate; writing debounces to avoid redundant history pushes. URL state survives page refresh and can be shared via copy-paste.

Import​

import { useSyncedSearchParams, buildSearchParams, parseSearchParams } from "@xocialive/ui-components/hooks";
import type { SearchParamConfig } from "@xocialive/ui-components/hooks";

Usage​

function UserListPage() {
  const [params, setParams] = useSyncedSearchParams({
    search: { type: "string", default: "" },
    page: { type: "number", default: 1 },
    status: { type: "string", default: "all" },
  });

  return (
    <>
      <GenericSearch value={params.search} onChange={(v) => setParams((p) => ({ ...p, search: v, page: 1 }))} />
      <StatusFilter value={params.status} onChange={(v) => setParams((p) => ({ ...p, status: v, page: 1 }))} />
    </>
  );
}

The URL will update to ?search=foo&page=1&status=active automatically.

SearchParamConfig​

type SearchParamConfig = {
  type: "string" | "number" | "boolean" | "array";
  default: string | number | boolean | string[];
};

Helper functions​

buildSearchParams(params)​

Converts a plain params object to a URLSearchParams string.

buildSearchParams({ page: 2, search: "alice" });
// → "page=2&search=alice"

parseSearchParams(search, config)​

Parses a URLSearchParams string into a typed object using the config schema.

parseSearchParams("page=2&search=alice", {
  page: { type: "number", default: 1 },
  search: { type: "string", default: "" },
});
// → { page: 2, search: "alice" }