use-param-sync
Demo

Type-safe URL state
& latest-wins async hooks

Keep UI state in the URL (not memory) and run async effects with automatic cancellation — so filters, pagination, and fetches stay always in sync.

Get StartedView Demo

Filters sync with URL • pagination is shareable • async calls are automatically cancelled

Installation

Tiny React 18+ utility for URL query state and safe async effects. Zero dependencies. Fully typed. ESM + CJS.

npm

pnpm

yarn

Peer dependency

Requires React 18+. Works with Next.js App Router, Vite, CRA, Remix, TanStack Router, and standard React applications.

Why developers use it

URL-driven state

State is stored in the query string (not duplicated in React state). Back/forward navigation works automatically.

Navigation-aware sync

popstate support ensures browser back/forward always restores correct UI state.

Typed serialization

Supports string, number, boolean, and string[] (comma-separated in URL). Fully inferred from initial state.

Debounced URL updates

Debounce applies ONLY to history updates — React state stays instant and responsive.

Zero runtime overhead

No dependencies. Tree-shakable ESM + CJS build with sideEffects: false.

Race-condition safe async

AbortController cancels previous requests automatically when dependencies change.

Real-world examples

Designed for search-heavy interfaces, dashboards, admin panels, data explorers, and async-driven React apps.

TanStack Query + URL state

Use URL-backed filters as your query key source for fully shareable and cache-friendly data fetching.

Query cache automatically follows URL state.

Simple URL state

The simplest possible usage. Perfect for search inputs, tabs, pagination, and shareable UI state.

Browser navigation automatically restores previous state.

TanStack Query mutations

Wrap mutation calls with useLatestAsync to ensure only the latest request resolves when users trigger rapid actions.

Prevents overlapping async mutations from resolving out of order.

Search + pagination + filters

Keep complex filters inside the URL so users can refresh, bookmark, share links, and navigate with browser history without losing UI state.

URL updates are debounced, but React state updates instantly.

Fetch requests without race conditions

Previous requests are automatically cancelled when filters change, preventing stale responses from overwriting fresh data.

Automatically passes AbortSignal to fetch when supported.

Axios integration

Axios v1+ supports AbortSignal, making cancellation work automatically with the same latest-wins behavior.

No stale responses. No manual cancellation logic.

Admin dashboard filters

Perfect for analytics dashboards, CRM systems, admin tables, and data-heavy applications with many synchronized filters.

Multiple hook instances can safely own different query params.

API

Two hooks. One for URL state. One for safe async.

useUrlState

Returns[state, setState]
debouncems (URL update delay only)
history"replace" | "push"

⚠️ debounce affects URL updates only — React state stays immediate

useLatestAsync

fnPromise or (signal) => Promise
depsLike useEffect dependencies
returnsdata, error, loading, run

Previous requests are automatically aborted when deps change