paramsync>overview

paramsync Documentation

A high-performance, type-safe URL Search Parameters state manager engineered for React 18+ and Next.js App Router applications.

0ms

0ms Typing Lag

Local input state responds instantly while URL updates are smoothly debounced in the background.

Auto-Purge

Clean URL Policy

Empty strings, empty arrays, and defaults are purged automatically from query strings.

Atomic

Batch Transitions

Commit multi-filter drawer updates atomically in one single Next.js navigation transition.

Installation

Install paramsync via your preferred package manager:

terminal

npm install paramsync
# or
pnpm add paramsync
# or
yarn add paramsync

main|paramsync

Shell Script|UTF-8|Ln 5, Col 1

Quick Start Example

Pair useQueryState with built-in parsers to bind state directly to URL search params:

TSSearchFeed.tsx

'use client';
 
import { useQueryState, parseAsString, parseAsInteger } from 'paramsync';
 
export default function SearchFeed() {
  // Live search with 300ms debounce
  const [search, setSearch] = useQueryState('q', parseAsString.withDefault(''), {
    debounceMs: 300,
  });
 
  // Numeric page index
  const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
 
  return (
    <div>
      <input
        type="text"
        value={search}
        onChange={(e) => {
          setPage(1); // auto-reset page on search
          setSearch(e.target.value);
        }}
        placeholder="Filter results..."
      />
    </div>
  );
}

main|paramsync

TypeScript JSX|UTF-8|Ln 27, Col 1

Built-in Parsers Reference

Each parser enforces strict runtime validation, TypeScript type narrowing, and Clean URL policy purging:

parseAsString

Standard string parameter parser with automatic empty string purging and debounce support.

parseAsInteger

Strict integer parser that guarantees safe, non-NaN integer state representations in URLs.

parseAsFloat

Floating-point number parser for decimals, ratings, geographical coordinates, and metrics.

parseAsBoolean

Boolean flag parser that maps truthy ("true", "1") and falsy ("false", "0") query values.

parseAsArray

Higher-order collection parser for multi-select facet filters, tags, and category lists.

parseAsNumberRange

Composite parser for dual-thumb numeric sliders, price spans, and min/max boundaries.

parseAsSort

Composite parser for tabular sort state, column sorting, and order direction.

createParser

Extensible factory for building bespoke domain parsers with full TypeScript inference.