paramsync>quick-start

Quick Start Tutorial

Learn how to bind query parameters to React state with zero typing latency in under 5 minutes.

Step 1: Import useQueryState and Parsers

Import useQueryState along with the built-in parser that matches your data type:

TSexample.tsx

'use client';
 
import { useQueryState, parseAsString, parseAsInteger } from 'paramsync';

main|paramsync

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

Step 2: Create a Debounced Search Input

Pass { debounceMs: 300 } to debounce URL updates while keeping local input state 100% instantaneous:

TSexample.tsx

const [search, setSearch] = useQueryState(
  'q',
  parseAsString.withDefault(''),
  { debounceMs: 300 }
);

main|paramsync

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

Step 3: Add Pagination with Auto-Reset

Reset page back to 1 when the search query changes so users don't end up on an empty page:

TSexample.tsx

const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
 
const handleSearch = (newVal: string) => {
  setPage(1); // Cleans ?page from URL
  setSearch(newVal);
};

main|paramsync

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

Complete Working Component

TSSearchFeed.tsx

'use client';
 
import { useQueryState, parseAsString, parseAsInteger } from 'paramsync';
 
export default function SearchFeed() {
  const [search, setSearch] = useQueryState(
    'q',
    parseAsString.withDefault(''),
    { debounceMs: 300 }
  );
 
  const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
 
  return (
    <div className="space-y-4">
      <input
        type="text"
        value={search}
        onChange={(e) => {
          setPage(1);
          setSearch(e.target.value);
        }}
        placeholder="Filter results..."
      />
 
      <div className="flex items-center gap-2">
        <button disabled={page <= 1} onClick={() => setPage((p) => p - 1)}>
          Prev
        </button>
        <span>Page {page}</span>
        <button onClick={() => setPage((p) => p + 1)}>
          Next
        </button>
      </div>
    </div>
  );
}

main|paramsync

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