ngx-query-params

Reactive and type-safe query parameter management using Angular Signals.

🔁 Two-way binding between URL query parameters and application state, powered by Angular’s modern reactivity model.

🚀 Features

• ✅ Auto-synced signals from query parameters
• ✅ Two-way binding: update signals → update URL
• ✅ Works with primitive types, arrays, booleans, numbers, enums, and more
• ✅ Fully tree-shakable, Angular-native
• ✅ Zero extra dependencies

📦 Installation

Using NPM:

npm install @geckosoft/ngx-query-params

Using YARN:

yarn add @geckosoft/ngx-query-params

🧩 Setup

Ensure your app uses Angular's Signals (Angular v17+).

No special setup needed—just import and use in any Angular component or service.

🧪 Usage

Bind a number param:

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { qpNum } from '@geckosoft/ngx-query-params';

@Component({
  selector: ...,
  imports: [FormsModule],
  template: `
    <input type="number" [(ngModel)]="page">
    <button (click)="nextPage()">Next Page</button>
  `,
})
export class MyComponent {
  page = qpNum('page', 1); // ?page=1

  nextPage() {
    this.page.set(this.page() + 1);
  }
}

Bind a boolean param:

toggle = qpBool('debug', false); // ?debug=true

Bind a string param:

filter = qp('filter', 'all'); // ?filter=all

Optional single param:

sort = qp('sort'); // string | undefined

Enum-like casting:

type Tab = 'home' | 'profile' | 'settings';
tab = qpCast1<Tab>('tab', 'home'); // ?tab=home

Multi-value param:

tags = qpMapN('tag', (x) => x.toLowerCase()); // ?tag=a&tag=b

🧠 How It Works

• Hooks into Angular Router's ActivatedRoute and queryParamMap
• Syncs with WritableSignal<T>
• A global QueryParamsService batches and updates the URL when any param changes

📦 API Reference

Signals

| Function | Type | Description | |------------------|-----------------------------------------|-------------------------------------| | qp() | WritableSignal<string \| undefined> | String param | | qpNum() | WritableSignal<number \| undefined> | Number param | | qpBool() | WritableSignal<boolean \| undefined> | Boolean param | | qpCast1<T>() | WritableSignal<T \| undefined> | Cast to enum/union type | | qpMapN() | WritableSignal<T[]> | Multi-value param with mapping | | qpMap1() | WritableSignal<T \| undefined> | Generic one-value mapper |

🔧 Advanced

You can inject QueryParamsService to manually batch or set multiple parameters:

constructor(private readonly qps: QueryParamsService) {}

applyFilters() {
  this.qps.set('filter', 'recent');
  this.qps.set('limit', 20);
}

🧼 Cleanup

No need to manually unsubscribe—internally handles onDestroy() and signal disposal.

📜 License

MIT

💬 Feedback / Contributions

Issues and PRs welcome!