react-magic-search-params

Type-safe query/search parameter management for React Router, built as an extension over useSearchParams.

Installation

npm install react-magic-search-params

Compatibility

• React 18.x and 19.x
• React Router DOM 6+
• Node.js 18+

Basic Usage

import { useMagicSearchParams } from 'react-magic-search-params';

const paramsUsers = {
  mandatory: {
    page: 1,
    page_size: 10 as const,
    only_is_active: false,
    tags: ['uno', 'dos', 'tres'] as string[],
  },
  optional: {
    search: '',
    order: '',
  },
};

const { getParams, updateParams, clearParams } = useMagicSearchParams({
  ...paramsUsers,
  defaultParams: paramsUsers.mandatory,
  forceParams: { page_size: 10 },
  arraySerialization: 'csv',
  omitParamsByValues: ['all', 'default'],
});

const { page, search, tags } = getParams({ convert: true });

updateParams({ newParams: { page: (page ?? 1) + 1 } });
updateParams({ newParams: { tags: 'react' } });
clearParams({ keepMandatoryParams: true });

If you have ambiguous optional unions (for example boolean | ''), use coerceParams:

const { getParams } = useMagicSearchParams({
  mandatory: { page: 1, page_size: 50 },
  optional: { only_unmapped: '' as boolean | '' },
  coerceParams: { only_unmapped: 'boolean' },
});

const { only_unmapped } = getParams({ convert: true });

API

• getParams({ convert?: boolean })
• getParam(key, { convert?: boolean })
• updateParams({ newParams?, keepParams? })
• clearParams({ keepMandatoryParams?: boolean })
• onChange(paramName, callbacks[])

Full Documentation

The full guide, advanced patterns, and detailed explanations are in the repository README:

https://github.com/Gabriel117343/react-magic-search-params