Parserparamsync > parsers

parseAsArray

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

TSTypeScript Signature

IntelliSense

parseAsArray<T>(itemParser: Parser<T>, separator?: string): ParserWithDefault<NonNullable<T>[]>

What it does

Accepts an underlying item parser (such as parseAsString or parseAsInteger) and splits delimited strings into a typed JavaScript array. Empty arrays `[]` are automatically purged from the query string.

Best For

Multi-select category checkboxes (?categories=audio,laptops)
Multiple tag selectors (?tags=react,nextjs,typescript)
Status badges filter (?status=open,in_review)
Multi-user selection filters

How to use it properly

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

TSExample.tsx

'use client';
 
import { useQueryState, parseAsArray, parseAsString } from 'paramsync';
 
const ALL_CATEGORIES = ['electronics', 'clothing', 'home', 'books'] as const;
 
export function CategoryFacet() {
  const [categories, setCategories] = useQueryState(
    'categories',
    parseAsArray(parseAsString)
  );
 
  const toggleCategory = (cat: string) => {
    setCategories((prev) =>
      prev.includes(cat) ? prev.filter((c) => c !== cat) : [...prev, cat]
    );
  };
 
  return (
    <div className="flex flex-wrap gap-1.5">
      {ALL_CATEGORIES.map((cat) => {
        const isActive = categories.includes(cat);
        return (
          <button
            key={cat}
            onClick={() => toggleCategory(cat)}
            className={`px-2.5 py-1 text-xs rounded border font-mono transition-colors ${
              isActive
                ? 'bg-zinc-100 text-zinc-900 border-zinc-100 font-medium'
                : 'bg-zinc-900 text-zinc-400 border-zinc-800 hover:border-zinc-700'
            }`}
          >
            {cat}
          </button>
        );
      })}
    </div>
  );
}

main|paramsync

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

Advanced Technique

Functional Updates & Dynamic State

TSAdvancedUsage.tsx

// Parsing array of numbers (e.g. ?ids=101,102,103)
const [ids, setIds] = useQueryState('ids', parseAsArray(parseAsInteger));

main|paramsync

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

Clean URL Behavior

When users clear all checkboxes or badges, the entire parameter is cleaned out of the URL.

State Condition	Clean URL Action	Resulting URL
categories.length === 0	Key removed completely from URL	https://example.com/store
categories === ["audio", "keyboards"]	Serialized as comma-separated values	https://example.com/store?categories=audio,keyboards

Configuration Parameters

Parameter	Type	Default	Description
itemParser	Parser<T>	-	Underlying parser for array items (e.g. parseAsString, parseAsInteger).
separator	string	","	Delimiter character between items. Defaults to comma `,`.

Related API References

parseAsString parseAsNumberRange