New `withUrlParamsSync` extension for URL-state synchronization

[yannickglt]

I've created a withUrlParamsSync extension for NgRx Signal Store that automatically synchronizes selected state properties with URL parameters (query params or route params). It works bidirectionally: state changes update the URL, and URL changes update the state.

Why?

• Users can share/bookmark URLs with filters, sorting, pagination preserved
• Direct navigation to specific application states
• No need to manually sync state ↔ URL in every component

Example

export const appRoutes: Route[] = [{
  path: 'visibility',
  data: { urlParamsSyncKey: 'todo-list' },
  loadComponent: () => …,
];

…

export const TodoListStore = signalStore(
  { providedIn: 'root' },
  withState(initialState),
  withUrlParamsSync<TodoListState>({
    key: 'todo-list', // Must match route.data['urlParamsSyncKey']
    select: (state) => ({
      'filters.search': state.filters.search,
      sortBy: state.sortBy,
      sortOrder: state.sortOrder,
    }),
    queryParamsKey: {
      'filters.search': 'search',
      sortBy: 'sort_by',
    },
    defaultValues: {
      'filters.search': null,
    },
    syncType: 'queryParams', // or 'routeParameters'
  }),
)

When filters.search changes, the URL updates to ?search=.... When the URL changes (e.g., user navigates back), the state updates automatically.

Features

• ✅ Bidirectional sync (state ↔ URL)
• ✅ Supports query params and route params
• ✅ Nested objects via dot notation (filters.search)
• ✅ Custom serialization/deserialization
• ✅ Default value filtering (keeps URLs clean)
• ✅ Key mapping (state key → URL param name)
• ✅ Only syncs when target route is active

Implementation

The code is production-ready and unit tested. We use if in production for a month.
I think it can be useful to share and your repository (I use on my own) sounds the good place to host it.

If you're interested, I can create a PR with the implementation.

Let me know if you'd like me to proceed and if there are rules to follow 🙂

[rainerhahnekamp]

I think @michael-small is the best one to response because he was already researching/working on something in that field.

[michael-small]

Thank you for this @yannickglt.

We have been discussing an RFC for routing sometime soon, so this comes at a great time. I had a more basic/less featured query param bidirectional sync, as well as a params sync in progress. But like I said, they are lowfi compared to this feature you are proposing.

For reference since I was working on a crude version of something like this, my take on a first draft of a query params syncer.

import { Params } from '@angular/router';
import { signalMethod, signalStore, signalStoreFeature, withHooks, withMethods } from '@ngrx/signals';

// It is not confirmed that we would pull in a dependency, 
// but this is what I have used in prod projects for this feature
import { injectQueryParams } from 'ngxtension/inject-query-params'; 

import { updateState, withDevtools } from '@angular-architects/ngrx-toolkit';
import { withImmutableState } from '@angular-architects/ngrx-toolkit';

type QueryParamsState = {
    id: string;
};

const initialState: QueryParamsState = {
    id: '',
};

export const withDefaultFilters = (p: Params): QueryParamsState => ({
    id p['id'] || '',
});

/**
 * @param filterFn Map default values to query params.
 * 
 * @example 
 * 
    type QueryParamsState = ...;
    const initialState: QueryParamsState = {
       id: '',
        // ...
    };

    // Although we give default `''` values anyways in a store's `initialState`, 
    // these fallback `''` are needed so that the param types are inferrable
    export const withDefaultFilters = (p: Params): QueryParamsState => ({
        id: p['id'] || '',
        // ...
    });

    export const QueryParamsStore = signalStore(
        // ...
        withImmutableState(initialState)
        withQueryParams(withDefaultFilters)
    );
 */
export function withQueryParams<T extends Record<string, string>>(filterFn: (p: Params) => T) {
    return signalStoreFeature(
        withMethods(store => ({
            // The more reactivve thing technically would be to make each computed, but this is convenient/functional
            _setQueryParams: signalMethod<T>(params => {
                updateState(store, 'set query params', { ...params });
            }),
        })),
        withHooks({
            onInit(store) {
                const queryParams = injectQueryParams(params => filterFn(params));
                store._setQueryParams(queryParams);
            },
        })
    );
}

export const QueryParamsStore = signalStore(
    { providedIn: 'root' },
    withDevtools('queryParams'),
    withImmutableState(initialState),
    withQueryParams(withDefaultFilters)
);

I'm thinking that query params + route params support in whatever form would be the bedrock of a routing support, and the basis of an RFC.

Seeing your withUrlParamsSync, I think it looks real promising. But before opening a PR, two things

1. What other maintainers like @rainerhahnekamp think about considering any particular implementation before a formal RFC. I'm really liking the preview of your proposed API, but I'm thinking we probably want to hold off on much further consideration until we can formally RFC a cohesive routing API for the Toolkit.
2. Some particulars about withUrlsParamsSync.
   • What does writing to a param look like? Is it just patching the respective selected piece of state like other patchable signal store state?
   • Does it have any dependencies? My own lofi solution has the bulk of its heavy lifting done via a dependency at the moment, but that is not a guarantee that it would be added without much discussion among us maintainers.
   • Before making a PR, a Stackblitz or some hosted example would probably cover a lot of other questions of ours as well as provide room for anyone to familiarize themselves.

In short, you bring this here at a great time, but this would likely be a contending piece of a greater routing RFC we were going to get to within the coming weeks.