feat(router): Update IsActiveMatchOptions APIs to accept a Partial

atscott · leonsenft · commit 907a94dcec29 · 2026-01-29T12:10:40.000-08:00
This updates `RouterLinkActive`, `Router.isActive`, and the standalone `isActive` function to accept `Partial<IsActiveMatchOptions>` which uses the current default values as the base (paths and queryParams are subset, fragment and matrix params are ignored). fixes #53326
diff --git a/goldens/public-api/router/index.api.md b/goldens/public-api/router/index.api.md
@@ -370,7 +370,7 @@ export interface InMemoryScrollingOptions {
 }
 
 // @public
-export function isActive(url: string | UrlTree, router: Router, matchOptions?: IsActiveMatchOptions): Signal<boolean>;
+export function isActive(url: string | UrlTree, router: Router, matchOptions?: Partial<IsActiveMatchOptions>): Signal<boolean>;
 
 // @public
 export interface IsActiveMatchOptions {
@@ -728,8 +728,8 @@ export class Router {
     initialNavigation(): void;
     // @deprecated
     isActive(url: string | UrlTree, exact: boolean): boolean;
-    // @deprecated
-    isActive(url: string | UrlTree, matchOptions: IsActiveMatchOptions): boolean;
+    // @deprecated (undocumented)
+    isActive(url: string | UrlTree, matchOptions: Partial<IsActiveMatchOptions>): boolean;
     get lastSuccessfulNavigation(): Signal<Navigation | null>;
     navigate(commands: readonly any[], extras?: NavigationExtras): Promise<boolean>;
     navigateByUrl(url: string | UrlTree, extras?: NavigationBehaviorOptions): Promise<boolean>;
@@ -885,7 +885,7 @@ export class RouterLinkActive implements OnChanges, OnDestroy, AfterContentInit
     set routerLinkActive(data: string[] | string);
     routerLinkActiveOptions: {
         exact: boolean;
-    } | IsActiveMatchOptions;
+    } | Partial<IsActiveMatchOptions>;
     // (undocumented)
     static ɵdir: i0.ɵɵDirectiveDeclaration<RouterLinkActive, "[routerLinkActive]", ["routerLinkActive"], { "routerLinkActiveOptions": { "alias": "routerLinkActiveOptions"; "required": false; }; "ariaCurrentWhenActive": { "alias": "ariaCurrentWhenActive"; "required": false; }; "routerLinkActive": { "alias": "routerLinkActive"; "required": false; }; }, { "isActiveChange": "isActiveChange"; }, ["links"], never, true, never>;
     // (undocumented)
diff --git a/packages/router/src/directives/router_link_active.ts b/packages/router/src/directives/router_link_active.ts
@@ -129,7 +129,9 @@ export class RouterLinkActive implements OnChanges, OnDestroy, AfterContentInit
    *
    * @see {@link isActive}
    */
-  @Input() routerLinkActiveOptions: {exact: boolean} | IsActiveMatchOptions = {exact: false};
+  @Input() routerLinkActiveOptions: {exact: boolean} | Partial<IsActiveMatchOptions> = {
+    exact: false,
+  };
 
   /**
    * Aria-current attribute to apply when the router link is active.
@@ -247,7 +249,9 @@ export class RouterLinkActive implements OnChanges, OnDestroy, AfterContentInit
   }
 
   private isLinkActive(router: Router): (link: RouterLink) => boolean {
-    const options: IsActiveMatchOptions = isActiveMatchOptions(this.routerLinkActiveOptions)
+    const options: Partial<IsActiveMatchOptions> = isActiveMatchOptions(
+      this.routerLinkActiveOptions,
+    )
       ? this.routerLinkActiveOptions
       : // While the types should disallow `undefined` here, it's possible without strict inputs
         (this.routerLinkActiveOptions.exact ?? false)
@@ -270,7 +274,8 @@ export class RouterLinkActive implements OnChanges, OnDestroy, AfterContentInit
  * Use instead of `'paths' in options` to be compatible with property renaming
  */
 function isActiveMatchOptions(
-  options: {exact: boolean} | IsActiveMatchOptions,
-): options is IsActiveMatchOptions {
-  return !!(options as IsActiveMatchOptions).paths;
+  options: {exact: boolean} | Partial<IsActiveMatchOptions>,
+): options is Partial<IsActiveMatchOptions> {
+  const o = options as Partial<IsActiveMatchOptions>;
+  return !!(o.paths || o.matrixParams || o.queryParams || o.fragment);
 }
diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts
@@ -608,25 +608,24 @@ export class Router {
    */
   isActive(url: string | UrlTree, exact: boolean): boolean;
   /**
-   * Returns whether the url is activated.
-   * @deprecated 21.1 - Use the `isActive` function instead.
    * @see {@link isActive}
+   * @deprecated 21.1 - Use the `isActive` function instead.
    */
-  isActive(url: string | UrlTree, matchOptions: IsActiveMatchOptions): boolean;
+  isActive(url: string | UrlTree, matchOptions: Partial<IsActiveMatchOptions>): boolean;
   /** @internal */
   isActive(url: string | UrlTree, matchOptions: boolean | IsActiveMatchOptions): boolean;
   /**
    * @deprecated 21.1 - Use the `isActive` function instead.
    * @see {@link isActive}
    */
-  isActive(url: string | UrlTree, matchOptions: boolean | IsActiveMatchOptions): boolean {
+  isActive(url: string | UrlTree, matchOptions: boolean | Partial<IsActiveMatchOptions>): boolean {
     let options: IsActiveMatchOptions;
     if (matchOptions === true) {
       options = {...exactMatchOptions};
     } else if (matchOptions === false) {
       options = {...subsetMatchOptions};
     } else {
-      options = matchOptions;
+      options = {...subsetMatchOptions, ...matchOptions};
     }
     if (isUrlTree(url)) {
       return containsTree(this.currentUrlTree, url, options);
diff --git a/packages/router/src/url_tree.ts b/packages/router/src/url_tree.ts
@@ -107,21 +107,26 @@ export const subsetMatchOptions: IsActiveMatchOptions = {
  *
  * As the router state changes, the signal will update to reflect whether the url is active.
  *
+ * When using the `matchOptions` argument, any missing properties fall back to the following defaults:
+ * - `paths`: 'subset'
+ * - `queryParams`: 'subset'
+ * - `matrixParams`: 'ignored'
+ * - `fragment`: 'ignored'
+ *
  * @see [Check if a URL is active](guide/routing/read-route-state#check-if-a-url-is-active)
  * @publicApi 21.1
  */
 export function isActive(
   url: string | UrlTree,
   router: Router,
-  matchOptions?: IsActiveMatchOptions,
+  matchOptions?: Partial<IsActiveMatchOptions>,
 ): Signal<boolean> {
   const urlTree = url instanceof UrlTree ? url : router.parseUrl(url);
   return computed(() =>
-    containsTree(
-      router.lastSuccessfulNavigation()?.finalUrl ?? new UrlTree(),
-      urlTree,
-      matchOptions ?? subsetMatchOptions,
-    ),
+    containsTree(router.lastSuccessfulNavigation()?.finalUrl ?? new UrlTree(), urlTree, {
+      ...subsetMatchOptions,
+      ...matchOptions,
+    }),
   );
 }
 
diff --git a/packages/router/test/router_link_active.spec.ts b/packages/router/test/router_link_active.spec.ts
@@ -24,4 +24,26 @@ describe('RouterLinkActive', () => {
     await fixture.whenStable();
     expect(Array.from(fixture.nativeElement.querySelector('a').classList)).toEqual([]);
   });
+
+  it('supports partial match options', async () => {
+    @Component({
+      imports: [RouterLinkActive, RouterLink],
+      template:
+        '<a routerLinkActive="active" [routerLinkActiveOptions]="{paths: \'exact\'}" routerLink="/abc"></a>',
+    })
+    class MyCmp {}
+
+    TestBed.configureTestingModule({providers: [provideRouter([{path: '**', children: []}])]});
+    const fixture = TestBed.createComponent(MyCmp);
+    fixture.autoDetectChanges();
+    const router = TestBed.inject(Router);
+    await router.navigateByUrl('/abc?q=1');
+    // paths: exact matches /abc
+    // queryParams: defaulted to subset (missing in /abc) -> match
+    // matrixParams: defaulted to ignored -> match
+    // fragment: defaulted to ignored -> match
+
+    await fixture.whenStable();
+    expect(Array.from(fixture.nativeElement.querySelector('a').classList)).toContain('active');
+  });
 });
diff --git a/packages/router/test/url_tree.spec.ts b/packages/router/test/url_tree.spec.ts
@@ -12,6 +12,7 @@ import {
   containsTree,
   DefaultUrlSerializer,
   exactMatchOptions,
+  isActive,
   subsetMatchOptions,
 } from '../src/url_tree';
 
@@ -147,6 +148,38 @@ describe('UrlTree', () => {
       });
     });
 
+    describe('isActive', () => {
+      it('should allow partial match options and use subset match options as default', () => {
+        const router = {
+          parseUrl: (url: string) => serializer.parse(url),
+          lastSuccessfulNavigation: () => ({finalUrl: serializer.parse('/one/two?a=1&b=2')}),
+        } as unknown as Router;
+
+        const t2 = serializer.parse('/one/two?a=1');
+
+        // With partial options: paths: 'exact'.
+        // derived options should be:
+        // paths: 'exact'
+        // queryParams: 'subset' (default)
+        // matrixParams: 'ignored' (default)
+        // fragment: 'ignored' (default)
+
+        // This should return true because paths match exactly, and queryParams is subset (t2 is subset of t1)
+        expect(isActive(t2, router, {paths: 'exact'})()).toBe(true);
+      });
+
+      it('should use subset match options as base for other properties', () => {
+        const router = {
+          parseUrl: (url: string) => serializer.parse(url),
+          lastSuccessfulNavigation: () => ({finalUrl: serializer.parse('/one/two#frag')}),
+        } as unknown as Router;
+        const t2 = serializer.parse('/one/two#diff');
+
+        // fragment is ignored by default in subsetMatchOptions
+        expect(isActive(t2, router, {paths: 'exact'})()).toBe(true);
+      });
+    });
+
     describe('exact = false', () => {
       it('should return true when containee is missing a segment', () => {
         const t1 = serializer.parse('/one/(two//left:three)(right:four)');
