feat(router): Add options optional parameter for withComponentInputBinding

Jordan Webster · mattrbeck · commit 89c9a4de308a · 2026-03-12T16:36:23.000-06:00
Add `ComponentInputBindingOptions` which is used with `withComponentInputBinding` and `bindToComponentInputs`
Can set which sources to bind as follows:
* queryParams
* params
* data

feat(router): Add `options` optional parameter for `withComponentInputBinding`

Add missing ternary operator for queryParams
diff --git a/goldens/public-api/router/index.api.md b/goldens/public-api/router/index.api.md
@@ -300,7 +300,7 @@ export enum EventType {
 
 // @public
 export interface ExtraOptions extends InMemoryScrollingOptions, RouterConfigOptions {
-    bindToComponentInputs?: boolean;
+    bindToComponentInputs?: boolean | ComponentInputBindingOptions;
     enableTracing?: boolean;
     enableViewTransitions?: boolean;
     errorHandler?: (error: any) => RedirectCommand | any;
@@ -1133,7 +1133,7 @@ export interface ViewTransitionsFeatureOptions {
 }
 
 // @public
-export function withComponentInputBinding(): ComponentInputBindingFeature;
+export function withComponentInputBinding(options?: ComponentInputBindingOptions): ComponentInputBindingFeature;
 
 // @public
 export function withDebugTracing(): DebugTracingFeature;
diff --git a/packages/router/src/directives/router_outlet.ts b/packages/router/src/directives/router_outlet.ts
@@ -27,14 +27,15 @@ import {
   SimpleChanges,
   ViewContainerRef,
 } from '@angular/core';
-import {combineLatest, of, Subscription} from 'rxjs';
+import {combineLatest, Observable, of, Subscription} from 'rxjs';
 import {switchMap} from 'rxjs/operators';
 
 import {RuntimeErrorCode} from '../errors';
 import {Data} from '../models';
 import {ChildrenOutletContexts} from '../router_outlet_context';
 import {ActivatedRoute} from '../router_state';
-import {PRIMARY_OUTLET} from '../shared';
+import {Params, PRIMARY_OUTLET} from '../shared';
+import {ComponentInputBindingOptions} from '../router_config';
 
 /**
  * An `InjectionToken` provided by the `RouterOutlet` and can be set using the `routerOutletData`
@@ -457,6 +458,10 @@ export const INPUT_BINDER = new InjectionToken<RoutedComponentInputBinder>(
 export class RoutedComponentInputBinder {
   private outletDataSubscriptions = new Map<RouterOutlet, Subscription>();
 
+  constructor(private options: ComponentInputBindingOptions) {
+    this.options.queryParams ??= true;
+  }
+
   bindActivatedRouteToOutletComponent(outlet: RouterOutlet): void {
     this.unsubscribeFromRouteData(outlet);
     this.subscribeToRouteData(outlet);
@@ -470,7 +475,7 @@ export class RoutedComponentInputBinder {
   private subscribeToRouteData(outlet: RouterOutlet) {
     const {activatedRoute} = outlet;
     const dataSubscription = combineLatest([
-      activatedRoute.queryParams,
+      this.options.queryParams ? activatedRoute.queryParams : of({}),
       activatedRoute.params,
       activatedRoute.data,
     ])
diff --git a/packages/router/src/provide_router.ts b/packages/router/src/provide_router.ts
@@ -41,7 +41,12 @@ import {RedirectCommand, Routes} from './models';
 import {NAVIGATION_ERROR_HANDLER, NavigationTransitions} from './navigation_transition';
 import {ROUTE_INJECTOR_CLEANUP, routeInjectorCleanup} from './route_injector_cleanup';
 import {Router} from './router';
-import {InMemoryScrollingOptions, ROUTER_CONFIGURATION, RouterConfigOptions} from './router_config';
+import {
+  ComponentInputBindingOptions,
+  InMemoryScrollingOptions,
+  ROUTER_CONFIGURATION,
+  RouterConfigOptions,
+} from './router_config';
 import {ROUTES} from './router_config_loader';
 import {PreloadingStrategy, RouterPreloader} from './router_preloader';
 
@@ -778,7 +783,8 @@ export type ViewTransitionsFeature = RouterFeature<RouterFeatureKind.ViewTransit
 
 /**
  * Enables binding information from the `Router` state directly to the inputs of the component in
- * `Route` configurations.
+ * `Route` configurations. Can also accept an `ComponentInputBindingOptions` object to set which
+ * sources are allowed to bind.
  *
  * @usageNotes
  *
@@ -811,13 +817,27 @@ export type ViewTransitionsFeature = RouterFeature<RouterFeatureKind.ViewTransit
  * Default values can be provided with a resolver on the route to ensure the value is always present
  * or an input and use an input transform in the component.
  *
+ * Advanced example of how you can disable binding from certain sources:
+ * ```ts
+ * const appRoutes: Routes = [];
+ * bootstrapApplication(AppComponent,
+ *   {
+ *     providers: [
+ *       provideRouter(appRoutes, withComponentInputBinding({queryParams: false}))
+ *     ]
+ *   }
+ * );
+ * ```
+ *
  * @see {@link /guide/components/inputs#input-transforms Input Transforms}
+ * @see {@link ComponentInputBindingOptions}
  * @returns A set of providers for use with `provideRouter`.
  */
-export function withComponentInputBinding(): ComponentInputBindingFeature {
+export function withComponentInputBinding(
+  options: ComponentInputBindingOptions = {},
+): ComponentInputBindingFeature {
   const providers = [
-    RoutedComponentInputBinder,
-    {provide: INPUT_BINDER, useExisting: RoutedComponentInputBinder},
+    {provide: INPUT_BINDER, useFactory: () => new RoutedComponentInputBinder(options)},
   ];
 
   return routerFeature(RouterFeatureKind.ComponentInputBindingFeature, providers);
diff --git a/packages/router/src/router_config.ts b/packages/router/src/router_config.ts
@@ -193,6 +193,22 @@ export interface InMemoryScrollingOptions {
   scrollPositionRestoration?: 'disabled' | 'enabled' | 'top';
 }
 
+/**
+ * Configuration options for the component input binding feature which can be used
+ * with `withComponentInputBinding` function or `RouterModule.forRoot`
+ *
+ * @publicApi
+ * @see withComponentInputBinding
+ * @see RouterModule#forRoot
+ */
+export interface ComponentInputBindingOptions {
+  /**
+   * When true (default), will configure query parameters to bind to component
+   * inputs.
+   */
+  queryParams?: boolean;
+}
+
 /**
  * A set of configuration options for a router module, provided in the
  * `forRoot()` method.
@@ -231,9 +247,10 @@ export interface ExtraOptions extends InMemoryScrollingOptions, RouterConfigOpti
 
   /**
    * When true, enables binding information from the `Router` state directly to the inputs of the
-   * component in `Route` configurations.
+   * component in `Route` configurations. Can also accept an `ComponentInputBindingOptions` object
+   * to set whether to exclude queryParams from binding.
    */
-  bindToComponentInputs?: boolean;
+  bindToComponentInputs?: boolean | ComponentInputBindingOptions;
 
   /**
    * When true, enables view transitions in the Router by running the route activation and
diff --git a/packages/router/src/router_module.ts b/packages/router/src/router_module.ts
@@ -152,7 +152,11 @@ export class RouterModule {
         provideRouterScroller(),
         config?.preloadingStrategy ? withPreloading(config.preloadingStrategy).ɵproviders : [],
         config?.initialNavigation ? provideInitialNavigation(config) : [],
-        config?.bindToComponentInputs ? withComponentInputBinding().ɵproviders : [],
+        config?.bindToComponentInputs
+          ? withComponentInputBinding(
+              typeof config.bindToComponentInputs === 'object' ? config.bindToComponentInputs : {},
+            ).ɵproviders
+          : [],
         config?.enableViewTransitions ? withViewTransitions().ɵproviders : [],
         provideRouterInitializer(),
       ],
diff --git a/packages/router/test/directives/router_outlet.spec.ts b/packages/router/test/directives/router_outlet.spec.ts
@@ -218,6 +218,29 @@ describe('component input binding', () => {
     expect(instance.language).toEqual(undefined);
   });
 
+  it('does not set component inputs from matching query params when queryParam inputs are disabled', async () => {
+    @Component({
+      template: '',
+      standalone: false,
+    })
+    class MyComponent {
+      @Input() language?: string;
+    }
+
+    TestBed.configureTestingModule({
+      providers: [
+        provideRouter(
+          [{path: '**', component: MyComponent}],
+          withComponentInputBinding({queryParams: false}),
+        ),
+      ],
+    });
+    const harness = await RouterTestingHarness.create();
+
+    const instance = await harness.navigateByUrl('/?language=french', MyComponent);
+    expect(instance.language).toEqual(undefined);
+  });
+
   it('sets component inputs from resolved and static data', async () => {
     @Component({
       template: '',
@@ -315,6 +338,51 @@ describe('component input binding', () => {
     expect(instance.result).toEqual('from query params');
   });
 
+  it('when keys conflict, sets inputs based on priority: data > path params > query params, with queryParams disabled', async () => {
+    @Component({
+      template: '',
+      standalone: false,
+    })
+    class MyComponent {
+      @Input() result?: string;
+    }
+
+    TestBed.configureTestingModule({
+      providers: [
+        provideRouter(
+          [
+            {
+              path: 'withData',
+              component: MyComponent,
+              data: {'result': 'from data'},
+            },
+            {
+              path: 'withoutData',
+              component: MyComponent,
+            },
+          ],
+          withComponentInputBinding({queryParams: false}),
+        ),
+      ],
+    });
+    const harness = await RouterTestingHarness.create();
+
+    let instance = await harness.navigateByUrl(
+      '/withData;result=from path param?result=from query params',
+      MyComponent,
+    );
+    expect(instance.result).toEqual('from data');
+
+    // Same component, different instance because it's a different route
+    instance = await harness.navigateByUrl(
+      '/withoutData;result=from path param?result=from query params',
+      MyComponent,
+    );
+    expect(instance.result).toEqual('from path param');
+    instance = await harness.navigateByUrl('/withoutData?result=from query params', MyComponent);
+    expect(instance.result).toEqual(undefined);
+  });
+
   it('does not write multiple times if two sources of conflicting keys both update', async () => {
     let resultLog: Array<string | undefined> = [];
     @Component({
