Parserparamsync > parsers

parseAsInteger

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

TSTypeScript Signature

IntelliSense

parseAsInteger: Parser<number | null>

What it does

Parses base-10 integer numbers from URL query strings. Rejects non-numeric characters, floating decimals, and NaN values, falling back safely to the specified default value or null.

Best For

Pagination page indices (?page=2)
Page size and limit selectors (?limit=25)
Quantity counters and step controllers
Numeric entity IDs in query-driven modals

How to use it properly

Import parseAsInteger from 'paramsync' and bind it to useQueryState:

TSExample.tsx

'use client';
 
import { useQueryState, parseAsInteger } from 'paramsync';
 
export function PaginationControls() {
  const [page, setPage] = useQueryState(
    'page',
    parseAsInteger.withDefault(1)
  );
 
  return (
    <div className="flex items-center gap-2">
      <button
        disabled={page <= 1}
        onClick={() => setPage((p) => Math.max(1, p - 1))}
        className="px-3 py-1.5 rounded border border-zinc-800 disabled:opacity-40"
      >
        Previous
      </button>
      <span className="font-mono text-sm">Page {page}</span>
      <button
        onClick={() => setPage((p) => p + 1)}
        className="px-3 py-1.5 rounded border border-zinc-800"
      >
        Next
      </button>
    </div>
  );
}

main|paramsync

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

Advanced Technique

Functional Updates & Dynamic State

TSAdvancedUsage.tsx

// Auto-reset page when filter changes
function handleFilterChange(newFilter: string) {
  setPage(1); // Cleanses ?page parameter from URL
  setFilter(newFilter);
}

main|paramsync

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

Clean URL Behavior

Default page 1 is purged so initial catalog pages remain cleanly canonical (`/catalog` instead of `/catalog?page=1`).

State Condition	Clean URL Action	Resulting URL
page === 1 (withDefault(1))	Key removed from URL	https://example.com/feed
page === 3	Serialized as integer	https://example.com/feed?page=3
URL contains malformed `?page=abc`	Falls back to 1 safely without crashing	Internal state = 1

Configuration Parameters

Parameter	Type	Default	Description
defaultValue	number	1	Integer fallback configured through .withDefault(number).

Related API References

parseAsFloat parseAsNumberRange