From ccaa9e5eb3e29cc6ca810f1bff6bab7e6bf12fe4 Mon Sep 17 00:00:00 2001
From: SkyZeroZx <73321943+SkyZeroZx@users.noreply.github.com>
Date: Thu, 16 Oct 2025 15:15:26 -0500
Subject: [PATCH] docs: add matrix parameters docs and examples (#64459)

PR Close #64459
---
 .../guide/routing/common-router-tasks.md      |  4 +-
 .../guide/routing/navigate-to-routes.md       | 11 +++++-
 .../content/guide/routing/read-route-state.md | 37 +++++++++++++++++++
 3 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/adev/src/content/guide/routing/common-router-tasks.md b/adev/src/content/guide/routing/common-router-tasks.md
index 1ae7d949da7..1015f9ebdbe 100644
--- a/adev/src/content/guide/routing/common-router-tasks.md
+++ b/adev/src/content/guide/routing/common-router-tasks.md
@@ -11,7 +11,7 @@ To edit an item, users click an Edit button, which opens an `EditGroceryItem` co
 You want that component to retrieve the `id` for the grocery item so it can display the right information to the user.
 
 Use a route to pass this type of information to your application components.
-To do so, you use the [`withComponentInputBinding`](api/router/withComponentInputBinding) feature with `provideRouter` or the `bindToComponentInputs` option of `RouterModule.forRoot`.
+To do so, you use the `withComponentInputBinding` feature with `provideRouter` or the `bindToComponentInputs` option of `RouterModule.forRoot`.
 
 To get information from a route:
 
@@ -104,6 +104,8 @@ Provide optional route parameters in an object, as in `{ foo: 'foo' }`:
 <a [routerLink]="['/crisis-center', { foo: 'foo' }]">Crisis Center</a>
 ```
 
+This syntax passes matrix parameters, which are optional parameters associated with a specific URL segment. Learn more about [matrix parameters](/guide/routing/read-route-state#matrix-parameters).
+
 These three examples cover the needs of an application with one level of routing.
 However, with a child router, such as in the crisis center, you create new link array possibilities.
 
diff --git a/adev/src/content/guide/routing/navigate-to-routes.md b/adev/src/content/guide/routing/navigate-to-routes.md
index 78daed10b00..6651cd1418a 100644
--- a/adev/src/content/guide/routing/navigate-to-routes.md
+++ b/adev/src/content/guide/routing/navigate-to-routes.md
@@ -5,6 +5,7 @@ The RouterLink directive is Angular's declarative approach to navigation. It all
 ## How to use RouterLink
 
 Instead of using regular anchor elements `<a>` with an `href` attribute, you add a RouterLink directive with the appropriate path in order to leverage Angular routing.
+
 ```angular-ts
 import {RouterLink} from '@angular/router';
 @Component({
@@ -99,6 +100,9 @@ export class AppDashboard {
     this.router.navigate(['/search'], {
       queryParams: { category: 'books', sort: 'price' }
     });
+
+    // With matrix parameters
+    this.router.navigate(['/products', { featured: true, onSale: true }]);
   }
 }
 ```
@@ -143,7 +147,7 @@ export class UserDetailComponent {
 
 The `router.navigateByUrl()` method provides a direct way to programmatically navigate using URL path strings rather than array segments. This method is ideal when you have a full URL path and need to perform absolute navigation, especially when working with externally provided URLs or deep linking scenarios.
 
-```angular-ts
+```ts
 // Standard route navigation
 router.navigateByUrl('/products);
 
@@ -155,11 +159,14 @@ router.navigateByUrl('/products/123?view=details#reviews');
 
 // Navigate with query parameters
 router.navigateByUrl('/search?category=books&sortBy=price');
+
+// With matrix parameters
+router.navigateByUrl('/sales-awesome;isOffer=true;showModal=false')
 ```
 
 In the event you need to replace the current URL in history, `navigateByUrl` also accepts a configuration object that has a `replaceUrl` option.
 
-```angular-ts
+```ts
 // Replace current URL in history
 router.navigateByUrl('/checkout', {
   replaceUrl: true
diff --git a/adev/src/content/guide/routing/read-route-state.md b/adev/src/content/guide/routing/read-route-state.md
index 2279405ee8a..85d74aebaa7 100644
--- a/adev/src/content/guide/routing/read-route-state.md
+++ b/adev/src/content/guide/routing/read-route-state.md
@@ -181,6 +181,43 @@ In this example, users can use a select element to sort the product list by name
 
 For more information, check out the [official docs on QueryParamsHandling](/api/router/QueryParamsHandling).
 
+### Matrix Parameters
+
+Matrix parameters are optional parameters that belong to a specific URL segment, rather than applying to the entire route. Unlike query parameters which appear after a `?` and apply globally, matrix parameters use semicolons (`;`) and are scoped to individual path segments.
+
+Matrix parameters are useful when you need to pass auxiliary data to a specific route segment without affecting the route definition or matching behavior. Like query parameters, they don't need to be defined in your route configuration.
+
+```ts
+// URL format: /path;key=value
+// Multiple parameters: /path;key1=value1;key2=value2
+
+// Navigate with matrix parameters
+this.router.navigate(['/awesome-products', { view: 'grid', filter: 'new' }]);
+// Results in URL: /awesome-products;view=grid;filter=new
+```
+
+**Using ActivatedRoute**
+
+```ts
+import { Component, inject } from '@angular/core';
+import { ActivatedRoute } from '@angular/router';
+
+@Component(/* ... */)
+export class AwesomeProducts  {
+  private route = inject(ActivatedRoute);
+
+  constructor() {
+    // Access matrix parameters via params
+    this.route.params.subscribe((params) => {
+      const view = params['view']; // e.g., 'grid'
+      const filter = params['filter']; // e.g., 'new'
+    });
+  }
+}
+```
+
+NOTE: As an alternative to using `ActivatedRoute`, matrix parameters are also bound to component inputs when using the `withComponentInputBinding`.
+
 ## Detect active current route with RouterLinkActive
 
 You can use the `RouterLinkActive` directive to dynamically style navigation elements based on the current active route. This is common in navigation elements to inform users what the active route is.