feat(router): adds browserUrl input support to router links

SkyZeroZx · web-flow · commit 3683902234ac · 2026-02-24T10:51:33.000-08:00
Enables specifying a custom browser URL for router links via a new input,
allowing navigation to use an explicit browser URL in navigation options.
diff --git a/goldens/public-api/router/index.api.md b/goldens/public-api/router/index.api.md
@@ -795,6 +795,7 @@ export type RouterHashLocationFeature = RouterFeature<RouterFeatureKind.RouterHa
 // @public
 class RouterLink implements OnChanges, OnDestroy {
     constructor(router: Router, route: ActivatedRoute, tabIndexAttribute: string | null | undefined, renderer: Renderer2, el: ElementRef, locationStrategy?: LocationStrategy | undefined);
+    browserUrl: i0.InputSignal<string | UrlTree | undefined>;
     set fragment(value: string | undefined);
     // (undocumented)
     get fragment(): string | undefined;
@@ -845,7 +846,7 @@ class RouterLink implements OnChanges, OnDestroy {
     // (undocumented)
     get urlTree(): UrlTree | null;
     // (undocumented)
-    static ɵdir: i0.ɵɵDirectiveDeclaration<RouterLink, "[routerLink]", never, { "target": { "alias": "target"; "required": false; }; "queryParams": { "alias": "queryParams"; "required": false; }; "fragment": { "alias": "fragment"; "required": false; }; "queryParamsHandling": { "alias": "queryParamsHandling"; "required": false; }; "state": { "alias": "state"; "required": false; }; "info": { "alias": "info"; "required": false; }; "relativeTo": { "alias": "relativeTo"; "required": false; }; "preserveFragment": { "alias": "preserveFragment"; "required": false; }; "skipLocationChange": { "alias": "skipLocationChange"; "required": false; }; "replaceUrl": { "alias": "replaceUrl"; "required": false; }; "routerLink": { "alias": "routerLink"; "required": false; }; }, {}, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RouterLink, "[routerLink]", never, { "target": { "alias": "target"; "required": false; }; "queryParams": { "alias": "queryParams"; "required": false; }; "fragment": { "alias": "fragment"; "required": false; }; "queryParamsHandling": { "alias": "queryParamsHandling"; "required": false; }; "state": { "alias": "state"; "required": false; }; "info": { "alias": "info"; "required": false; }; "relativeTo": { "alias": "relativeTo"; "required": false; }; "preserveFragment": { "alias": "preserveFragment"; "required": false; }; "skipLocationChange": { "alias": "skipLocationChange"; "required": false; }; "replaceUrl": { "alias": "replaceUrl"; "required": false; }; "browserUrl": { "alias": "browserUrl"; "required": false; "isSignal": true; }; "routerLink": { "alias": "routerLink"; "required": false; }; }, {}, never, never, true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<RouterLink, [null, null, { attribute: "tabindex"; }, null, null, null]>;
 }
diff --git a/packages/router/src/directives/router_link.ts b/packages/router/src/directives/router_link.ts
@@ -28,6 +28,7 @@ import {
   untracked,
   ɵINTERNAL_APPLICATION_ERROR_HANDLER,
   ɵRuntimeError as RuntimeError,
+  input,
 } from '@angular/core';
 import {Subject} from 'rxjs';
 
@@ -353,6 +354,14 @@ export class RouterLink implements OnChanges, OnDestroy {
   }
   private _replaceUrl = signal<boolean>(false);
 
+  /**
+   * Passed to {@link Router#navigateByUrl} as part of the
+   * `NavigationBehaviorOptions`.
+   * @see {@link NavigationBehaviorOptions#browserUrl}
+   * @see {@link Router#navigateByUrl}
+   */
+  browserUrl = input<UrlTree | string | undefined>(undefined);
+
   /**
    * Whether a host element is an `<a>`/`<area>` tag or a compatible custom
    * element.
@@ -490,11 +499,15 @@ export class RouterLink implements OnChanges, OnDestroy {
       }
     }
 
+    const browserUrl = this.browserUrl();
     const extras = {
       skipLocationChange: this.skipLocationChange,
       replaceUrl: this.replaceUrl,
       state: this.state,
       info: this.info,
+      // TODO: Remove conditional spread once all consumers handle `browserUrl`.
+      // Having this property always set broke some tests in G3.
+      ...(browserUrl !== undefined && {browserUrl}),
     };
     // navigateByUrl is mocked frequently in tests... Reduce breakages when
     // adding `catch`
diff --git a/packages/router/test/integration/integration_helpers.ts b/packages/router/test/integration/integration_helpers.ts
@@ -142,6 +142,20 @@ export class LinkWithState {}
 })
 export class DivLinkWithState {}
 
+@Component({
+  selector: 'link-cmp',
+  template: `<a id="link" [routerLink]="['../simple']" [browserUrl]="'/custom'">link</a>`,
+  standalone: false,
+})
+export class LinkWithBrowserUrl {}
+
+@Component({
+  selector: 'div-link-cmp',
+  template: `<div id="link" [routerLink]="['../simple']" [browserUrl]="'/custom'">link</div>`,
+  standalone: false,
+})
+export class DivLinkWithBrowserUrl {}
+
 @Component({
   selector: 'simple-cmp',
   template: `simple`,
@@ -433,6 +447,8 @@ export class LazyComponent {}
     LinkWithQueryParamsAndFragment,
     DivLinkWithState,
     LinkWithState,
+    DivLinkWithBrowserUrl,
+    LinkWithBrowserUrl,
     CollectParamsCmp,
     QueryParamsAndFragmentCmp,
     StringLinkButtonCmp,
@@ -465,6 +481,8 @@ export class LazyComponent {}
     LinkWithQueryParamsAndFragment,
     DivLinkWithState,
     LinkWithState,
+    DivLinkWithBrowserUrl,
+    LinkWithBrowserUrl,
     CollectParamsCmp,
     QueryParamsAndFragmentCmp,
     StringLinkButtonCmp,
diff --git a/packages/router/test/integration/router_links.spec.ts b/packages/router/test/integration/router_links.spec.ts
@@ -26,6 +26,8 @@ import {
   DivLinkWithState,
   createRoot,
   advance,
+  DivLinkWithBrowserUrl,
+  LinkWithBrowserUrl,
 } from './integration_helpers';
 
 export function routerLinkIntegrationSpec() {
@@ -422,6 +424,47 @@ export function routerLinkIntegrationSpec() {
         expect(location.getState()).toEqual({foo: 'bar', navigationId: 3});
       });
     });
+    describe('should support browserUrl', () => {
+      let component: typeof LinkWithBrowserUrl | typeof DivLinkWithBrowserUrl;
+      it('for anchor elements', () => {
+        // Test logic in afterEach to reduce duplication
+        component = LinkWithBrowserUrl;
+      });
+
+      it('for non-anchor elements', () => {
+        // Test logic in afterEach to reduce duplication
+        component = DivLinkWithBrowserUrl;
+      });
+
+      afterEach(async () => {
+        const router: Router = TestBed.inject(Router);
+        const location: Location = TestBed.inject(Location);
+        const fixture = await createRoot(router, RootCmp);
+
+        router.resetConfig([
+          {
+            path: 'team/:id',
+            component: TeamCmp,
+            children: [
+              {path: 'link', component},
+              {path: 'simple', component: SimpleCmp},
+            ],
+          },
+        ]);
+
+        router.navigateByUrl('/team/22/link');
+        await advance(fixture);
+
+        const native = fixture.nativeElement.querySelector('#link');
+        native.click();
+        await advance(fixture);
+
+        expect(fixture.nativeElement).toHaveText('team 22 [ simple, right:  ]');
+
+        // Check the browser URL is the custom browserUrl value
+        expect(location.path()).toEqual('/custom');
+      });
+    });
 
     it('should set href on area elements', async () => {
       @Component({
