Skip to content

[go_router] docs: Document regex constraints on path parameters (flutter#177766) #11722

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
NadeemIqbal wants to merge 2 commits into
base: main
Choose a base branch
from
+9 −0
Draft

[go_router] docs: Document regex constraints on path parameters (flutter#177766) #11722

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef67a09
[go_router] docs: Document regex constraints on path parameters
NadeemIqbal May 17, 2026
822e01f
[go_router] docs: Use "nested parentheses" wording in regex path para…
NadeemIqbal May 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions packages/go_router/lib/src/route.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,6 +361,15 @@ 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)`. The parameter only matches if the corresponding path
/// segment also matches the regular expression — segments that fail the
/// pattern fall through to other route candidates. For example,
/// `/users/:id(\d+)` matches `/users/42` but not `/users/alice`. The
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The example path contains a backslash (\d). In Dart, this requires using a raw string literal or escaping the backslash to avoid an 'Invalid escape sequence' error. Using the raw string prefix r in the documentation makes the example more accurate and easier for developers to use directly.

Suggested change
/// `/users/:id(\d+)` matches `/users/42` but not `/users/alice`. The
/// `r'/users/:id(\d+)'` matches `/users/42` but not `/users/alice`. The

/// expression must not introduce its own capturing groups; everything
/// between the parentheses is interpreted as a Dart [RegExp] body.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot May 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The current implementation of the path parser (_parameterRegExp in path_utils.dart) does not support un-escaped nested parentheses. Additionally, the internal escaping of characters like :, =, and ! prevents the use of advanced features such as non-capturing groups ((?:...)) or lookarounds. It is more accurate to state that the expression must not contain nested parentheses.

Suggested change
/// expression must not introduce its own capturing groups; everything
/// between the parentheses is interpreted as a Dart [RegExp] body.
/// expression must not contain nested parentheses; everything
/// between the parentheses is interpreted as a Dart [RegExp] body.

///
/// The query parameter are also capture during the route parsing and stored
/// in [GoRouterState].
///
Expand Down