stateful-params/README.md

A lightweight and intuitive React hook for managing URL query parameters with ease. Stateful-params enables seamless CRUD operations on URL query parameters while keeping your UI in sync with the URL state. Perfect for building dynamic, stateful, and shar

# stateful-params

A lightweight and intuitive React hook for managing URL query parameters with ease. Stateful-params enables seamless CRUD operations on URL query parameters while keeping your UI in sync with the URL state. Perfect for building dynamic, stateful, and shareable UIs without the hassle of manual URL manipulation.

## Features

- **Stateful URL Management:** Automatically reflects changes in the URL and keeps your app state in sync.
- **CRUD Operations:** Easily create, read, update, and delete URL parameters.
- **Lightweight:** Minimal footprint, maximum utility.
- **Dynamic UIs:** Simplify building UIs that depend on URL parameters.

## Installation

Install the package using npm:

```bash
npm install stateful-params
```

## Usage

### Basic Example

```tsx
import { useStatefulParams } from "stateful-params"

const MyComponent = () => {
  const { set, get, deleteParam, append, searchParams } = useStatefulParams<{
    filter: string
    sort: string
    tags: string[]
  }>()

  const handleSetParam = () => {
    set({ filter: "active", sort: "asc" })
  }

  const handleAppendParam = () => {
    append({ tags: ["react", "hooks"] })
  }

  const handleDeleteParam = () => {
    deleteParam("filter")
  }

  return (
    <div>
      <h1>Current Params: {JSON.stringify(searchParams)}</h1>
      <button onClick={handleSetParam}>Set Params</button>
      <button onClick={handleAppendParam}>Append Params</button>
      <button onClick={handleDeleteParam}>Delete Param</button>
      <p>Filter: {get("filter") || "Not set"}</p>
    </div>
  )
}
```

## API Documentation

### `useStatefulParams(options)`

A hook for managing URL query parameters with options to update the router.

#### Parameters

- `options` (optional): Configuration options.
  - `deleteFalseValues` (boolean, default: `true`): Whether to delete the parameter if the parameter value is a false value.
  - `method` ("replace" | "push", default: `push`): Method to use for router update.

#### Returns

An object containing the following methods and properties:

- `set(params)`: Sets multiple query parameters at once.

  - `params`: An object containing parameter key-value pairs to set.
  - Returns the new query string after setting the parameters.

- `append(params)`: Appends values to existing query parameters or adds new ones.

  - `params`: An object containing parameter key-value pairs to append.
  - Returns the new query string after appending the parameters.

- `deleteParam(keys)`: Removes specified query parameters.

  - `keys`: The key or array of keys to remove from the query parameters.
  - Returns the new query string after deleting the specified parameters.

- `clear()`: Clears all query parameters.

  - Returns the new query string after clearing all parameters.

- `get(key)`: Retrieves the value of a specified query parameter.

  - `key`: The key of the query parameter to retrieve.
  - Returns the value of the specified query parameter, or `null` if not found.

- `searchParams`: An object representation of the current query parameters.

## Example Use Cases

- **Filtering and Sorting:** Persist filter and sort states in the URL for shareable links.
- **Dynamic UIs:** Build UIs that react to URL changes, such as tabs or modals.
- **Pagination:** Manage pagination state in the URL for better navigation.

## Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

## License

This project is licensed under the MIT License. See the LICENSE file for details.

## Author

[@Ahmed Hassan](https://www.linkedin.com/in/ahmedhassan711)