useUrlParams


A lightweight React hook library for managing URL query parameters with full TypeScript support and auto-generated helper methods.

Built for react-router-dom (v6+) with type-safe keys, option validation, and handy helper flags.

The library provides two hooks:
- useUrlParams - Manage a single query parameter
- useBulkUrlParams - Manage multiple query parameters at once

---

Features

- Type-safe query parameter keys and values
- Auto-generated helpers: set, toggle, is, clear
- Toggle mode for 2-option parameters
- Works seamlessly with react-router-dom’s useSearchParams
- Zero dependencies (except React & react-router-dom)

---

Installation

``bash
npm install react-url-query-params
`
or
`bash
yarn add react-url-query-params
`


Usage

!Demo of react-url-query-params

$3

`tsx
import { useUrlParams } from 'react-url-query-params';

export default function MyComponent() {
const { view, setView, toggleView, clearView, isViewGrid, isViewTable } = useUrlParams({
keyName: 'view',
options: ['grid', 'table'],
});

return (


`tsx
import { useBulkUrlParams } from 'react-url-query-params';

export default function MyComponent() {
const { set, isViewGrid, isViewTable, isModalOpened, isModalClosed } = useBulkUrlParams({
view: ['grid', 'table'],
modal: ['opened', 'closed'],
});

return (


| Option | Type | Description |
|--------------|-----------------------------------|-------------|
| keyName | string | Query parameter key |
| options | readonly string[] | Allowed values for this param |

Returns:
- [keyName] — current value (string or null)
- set — function to set a value
- First parameter: The value to set
- Second parameter (optional): { replace: boolean } - Controls browser history behavior
- replace: false (default) - Adds a new entry to browser history
- replace: true - Replaces the current history entry
- toggle — toggle between 2 allowed values (only works if options.length === 2)
- Parameter (optional): { replace: boolean } - Controls browser history behavior
- clear — function to clear parameter from url
- Parameter (optional): { replace: boolean } - Controls browser history behavior
- is — boolean helper for quick checks

Example:
`tsx
const { view, setView, toggleView, clearView, isViewGrid, isViewTable } = useUrlParams({
keyName: 'view',
options: ['grid', 'table'],
});

// Basic usage
setView('grid');
toggleView();
clearView();

// Control browser history
setView('grid', { replace: true });
toggleView({ replace: true });
clearView({ replace: true });
`

---

$3

Manage multiple query parameters simultaneously with a single hook.

Config:

A record object where:
- Keys are the query parameter names (e.g., 'view', 'modal')
- Values are readonly arrays of allowed values (e.g., ['grid', 'table'])


Returns:

- set — function to update one or more parameters at once
- First parameter: A partial object of key-value pairs
- Second parameter (optional): { replace: boolean } - Controls browser history behavior
- replace: false (default) - Adds a new entry to browser history
- replace: true - Replaces the current history entry
- Only updates the specified parameters, leaving others unchanged
- is — boolean flags for each key-option combination
- Automatically generated based on your config
- Format: is${Capitalize}${Capitalize}
- Example: For view: ['grid', 'table'], you get isViewGrid and isViewTable

Examples:

`tsx
// Basic usage
const { set, isViewGrid, isViewTable, clearParams } = useBulkUrlParams({
view: ['grid', 'table'],
});

// Multiple parameters
const { set, isViewGrid, isViewTable, isModalOpened, isModalClosed, clearParams } = useBulkUrlParams({
view: ['grid', 'table'],
modal: ['opened', 'closed'],
});

// Update single parameter
set({ view: 'grid' });

// Update multiple parameters at once
set({ view: 'table', modal: 'opened' });

// Control browser history (replace current entry instead of adding new one)
set({ view: 'grid' }, { replace: true });

// Use boolean flags
if (isViewGrid && isModalOpened) {
// Both conditions are true
}
`

Advanced Example:

`tsx
import { useBulkUrlParams } from 'react-url-query-params';

function FilterableTable() {
const { set, isSortAsc, isSortDesc, isFilterActive, isFilterInactive, clearParams } = useBulkUrlParams({
sort: ['asc', 'desc'],
filter: ['active', 'inactive'],
});

return (


Notes:
- Use as const for the options arrays to get the best TypeScript inference
- The clearParams function will clear all params declared in hook
- The set function accepts an optional second parameter { replace: boolean } to control browser history:
- replace: false (default) - Adds a new entry to browser history (users can use back button)
- replace: true` - Replaces the current history entry (prevents back button navigation to previous state)
- Boolean flags are automatically generated and update reactively when URL changes
- All parameter names and values are type-safe based on your config

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

MIT © Pavlo Kuzina

🔗 Links

- npm Package: react-url-query-params
- Repository: GitHub - utils-kit
- Issues: GitHub Issues
- Monorepo: Part of utils-kit collection

---

Related Packages

- react-csv-autopilot - A React library for exporting large datasets to CSV with automatic pagination, streaming, and progress tracking. Built with Web Workers for non-blocking performance and File System Access API for efficient file writing

---