From d21d9041954c3ac44f65c4296a74cc808fb1bf77 Mon Sep 17 00:00:00 2001
From: saurabh-mirajkar <saurabhmirajkar000@gmail.com>
Date: Fri, 24 Jul 2026 16:12:07 +0530
Subject: [PATCH] [go_router] Document regex constraints for path parameters

---
 .../example/lib/path_parameter_regex.dart     | 30 +++++++++++++++++++
 .../test/path_parameter_regex_test.dart       | 13 ++++++++
 packages/go_router/lib/src/route.dart         | 15 ++++++++++
 .../change_2026_07_24_1784894419364.yaml      |  3 ++
 4 files changed, 61 insertions(+)
 create mode 100644 packages/go_router/example/lib/path_parameter_regex.dart
 create mode 100644 packages/go_router/example/test/path_parameter_regex_test.dart
 create mode 100644 packages/go_router/pending_changelogs/change_2026_07_24_1784894419364.yaml

diff --git a/packages/go_router/example/lib/path_parameter_regex.dart b/packages/go_router/example/lib/path_parameter_regex.dart
new file mode 100644
index 000000000000..30b614d9110d
--- /dev/null
+++ b/packages/go_router/example/lib/path_parameter_regex.dart
@@ -0,0 +1,30 @@
+import 'package:flutter/material.dart';
+import 'package:go_router/go_router.dart';
+
+/// Router configuration demonstrating regex-constrained path parameters.
+final GoRouter router = GoRouter(
+  routes: <GoRoute>[
+    GoRoute(
+      path: r'/users/:id(\d+)',
+      builder: (BuildContext context, GoRouterState state) {
+        return Scaffold(body: Center(child: Text('User ${state.pathParameters['id']}')));
+      },
+    ),
+  ],
+);
+
+/// Runs the path parameter regular expression example.
+void main() {
+  runApp(const PathParameterRegexApp());
+}
+
+/// A minimal app demonstrating regex-constrained path parameters.
+class PathParameterRegexApp extends StatelessWidget {
+  /// Creates a [PathParameterRegexApp].
+  const PathParameterRegexApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(routerConfig: router);
+  }
+}
diff --git a/packages/go_router/example/test/path_parameter_regex_test.dart b/packages/go_router/example/test/path_parameter_regex_test.dart
new file mode 100644
index 000000000000..888c4824e696
--- /dev/null
+++ b/packages/go_router/example/test/path_parameter_regex_test.dart
@@ -0,0 +1,13 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:go_router_examples/path_parameter_regex.dart' as example;
+
+void main() {
+  testWidgets('matches numeric path parameter', (WidgetTester tester) async {
+    example.router.go('/users/42');
+
+    await tester.pumpWidget(const example.PathParameterRegexApp());
+    await tester.pumpAndSettle();
+
+    expect(find.text('User 42'), findsOneWidget);
+  });
+}
diff --git a/packages/go_router/lib/src/route.dart b/packages/go_router/lib/src/route.dart
index 6d75560a93cd..25389f368584 100644
--- a/packages/go_router/lib/src/route.dart
+++ b/packages/go_router/lib/src/route.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: doc_directive_unknown
+
 import 'dart:async';
 
 import 'package:collection/collection.dart';
@@ -341,6 +343,19 @@ class GoRoute extends RouteBase {
   /// `/family/456` and etc. The parameter values are stored in [GoRouterState]
   /// that are passed into [pageBuilder] and [builder].
   ///
+  /// A path parameter may optionally be constrained to a regular expression
+  /// by appending the expression in parentheses after the parameter name:
+  /// `:paramName(regex)`.
+  ///
+  /// {@example /example/lib/path_parameter_regex.dart}
+  ///
+  /// The path matches `/users/42` but not `/users/settings`. If a path segment
+  /// does not satisfy the regular expression, route matching continues with
+  /// other route candidates.
+  ///
+  /// The regular expression is interpreted as a Dart [RegExp] pattern and must
+  /// not contain nested parentheses.
+  ///
   /// The query parameter are also capture during the route parsing and stored
   /// in [GoRouterState].
   ///
diff --git a/packages/go_router/pending_changelogs/change_2026_07_24_1784894419364.yaml b/packages/go_router/pending_changelogs/change_2026_07_24_1784894419364.yaml
new file mode 100644
index 000000000000..826bd572d403
--- /dev/null
+++ b/packages/go_router/pending_changelogs/change_2026_07_24_1784894419364.yaml
@@ -0,0 +1,3 @@
+changelog: |
+  - Documents support for regular expression constraints in GoRoute path parameters.
+version: patch