react-magic-search-params 🪄

Centralize and type your search parameters (query params) handling in React Router v6+ with TypeScript.

---

📖 Introduction

useMagicSearchParams allows you to:

• Define required and optional parameters in one place.
• Get typed values (number, string, boolean, array).
• Update or clear the URL without repeating logic.
• Serialize arrays in csv, repeat or brackets format.
• Force values (forceParams) or omit neutral values (omitParamsByValues).

---

🚀 Installation

npm install react-magic-search-params

Basic Usage

import { useMagicSearchParams } from 'react-magic-search-params';
import { paramsUsers } from './constants';

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

// Get typed values:
const { page, search, tags } = getParams({ convert: true });

// Change page:
updateParams({ newParams: { page: (page ?? 1) + 1 } });

// Clear filters:
clearParams();

📁 Recommended Constants File

type UserTagOptions = 'tag1' | 'tag2' | 'react' | 'node' | 'typescript' | 'javascript';
type OrderUserProps = 'role' | 'date';

export const paramsUsers = {
  mandatory: { 
    page: 1,
    page_size: 10 as const,
    only_is_active: false,
  },
  optional:  { 
    order: '' as OrderUserProps,
    search: '',
    tags: ['tag1','tag2'] as Array<UserTagOptions>
  },
};

🌟 Key Functions

• getParams(opts?) → returns typed params.
• updateParams({ newParams, keepParams? }) → updates the URL.
• clearParams({ keepMandatoryParams? }) → clears parameters.
• onChange(key, callbacks[]) → subscribes to parameter changes.

---

🔄 Array Serialization

Method	Example URL
csv	tags=tag1,tag2,tag3
repeat	tags=tag1&tags=tag2&tags=tag3
brackets	tags[]=tag1&tags[]=tag2&tags[]=tag3

🔗 Complete Documentation

Find the complete guide and examples on GitHub:
https://github.com/Gabriel117343/react-magic-search-params

If you found this library helpful, please give it a ⭐️ on GitHub!