Parserparamsync > parsers

createParser

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

TSTypeScript Signature

IntelliSense

createParser<T>(options: { parse: (val: string | null) => T; serialize: (val: T) => string; defaultValue?: T }): Parser<T>

What it does

Provides the low-level primitive for building custom parsers. Implements bi-directional parse and serialize logic, automatic null handling, and equips your custom parser with the .withDefault() method automatically.

Best For

Complex objects or JSON query parameters
Date and ISO timestamp parsing (Date objects)
Custom TypeScript enums and literal union types
Encrypted or base64-encoded URL parameters

How to use it properly

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

TSExample.tsx

'use client';
 
import { createParser, useQueryState } from 'paramsync';
 
// Custom Date parser that handles ISO strings
const parseAsIsoDate = createParser<Date | null>({
  parse: (val) => (val ? new Date(val) : null),
  serialize: (val) => (val ? val.toISOString().split('T')[0] : ''),
});
 
export function DatePickerFilter() {
  const [selectedDate, setSelectedDate] = useQueryState('date', parseAsIsoDate);
 
  return (
    <input
      type="date"
      value={selectedDate ? selectedDate.toISOString().split('T')[0] : ''}
      onChange={(e) =>
        setSelectedDate(e.target.value ? new Date(e.target.value) : null)
      }
      className="bg-zinc-900 border border-zinc-800 rounded px-3 py-1.5 text-zinc-100"
    />
  );
}

main|paramsync

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

Clean URL Behavior

Values matching the default value or returning empty string from serialize are purged.

State Condition	Clean URL Action	Resulting URL
serialize(value) === "" or value === defaultValue	Key removed from URL	https://example.com/app

Related API References

parseAsString parseAsArray