[go_router] Document regex constraints for path parameters

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);
+  }
+}

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);
+  });
+}

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].
   ///

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