useBatchQueryParams
Hookparamsync > hooks

useBatchQueryParams

Atomic multi-parameter manager committing multiple URL updates in a single Next.js navigation transition.

TSTypeScript Signature
IntelliSense
useBatchQueryParams(options?: UseBatchQueryParamsOptions): { setBatchParams, resetAllParams, isPending }

What it does

Solves the problem of updating multiple query parameters sequentially (which causes multiple router transitions and re-renders). Allows modifying, adding, or deleting multiple keys simultaneously in one atomic history step. Ideal for "Apply Filters" modal/drawer buttons and reset-all buttons.

Best For

  • Filter drawers and slide-over panels with an "Apply" button
  • Batch filter resetting (Clear All Filters)
  • Multi-facet dashboard views
  • Complex query presets and saved bookmarks

Configuration Options

OptionTypeDefaultDescription
history'replace' | 'push''replace'Navigation mode. 'replace' modifies current URL; 'push' pushes new entry into browser history.
scrollbooleanfalseWhether to scroll to top after committing the batch update.

Return Values

Return ValueTypeDescription
setBatchParams(updates: BatchParamsRecord, navOptions?: BatchNavigationOptions) => voidCommits multiple parameter updates at once. Passing null as a value deletes that parameter from the URL.
resetAllParams(preserveKeys?: string[], navOptions?: BatchNavigationOptions) => voidRemoves all query parameters from the URL at once, optionally preserving specific keys like ?tab= or ?utm_source=.
isPendingbooleanReact useTransition state indicating when the atomic batch navigation is in flight.

Usage Example

TSuseBatchQueryParamsExample.tsx
'use client';
 
import {
  useBatchQueryParams,
  parseAsArray,
  parseAsString,
  parseAsNumberRange,
} from 'paramsync';
 
export function FilterDrawer({ draftFilters, onClose }) {
  const { setBatchParams, resetAllParams, isPending } = useBatchQueryParams();
 
  const handleApply = () => {
    // Commit 4 updates in 1 single router transition:
    setBatchParams({
      q: draftFilters.keyword || null,
      category: {
        value: draftFilters.categories,
        parser: parseAsArray(parseAsString),
      },
      price: {
        value: draftFilters.priceRange,
        parser: parseAsNumberRange(0, 1000),
      },
      page: null, // Deletes 'page' parameter to reset to page 1
    });
    onClose();
  };
 
  return (
    <div>
      <button onClick={handleApply} disabled={isPending}>
        {isPending ? 'Applying...' : 'Apply All (1 Transition)'}
      </button>
      <button onClick={() => resetAllParams(['utm_source'])}>
        Reset All
      </button>
    </div>
  );
}
main|paramsync
TypeScript JSXLn 40, Col 1

Advanced Techniques

TSexample.tsx
// Preserving certain keys when clearing filters:
resetAllParams(['tab', 'viewMode']);
main|paramsync
TypeScript JSXLn 2, Col 1
;