blob: ad6fadd9473e8fa93f350afe115c247955f15cf3 [file] [log] [blame] [view]
Create a GoRouter configuration by calling the [GoRouter][] constructor and
providing list of [GoRoute][] objects:
```dart
GoRouter(
routes: [
GoRoute(
path: '/',
builder: (context, state) => const Page1Screen(),
),
GoRoute(
path: '/page2',
builder: (context, state) => const Page2Screen(),
),
],
);
```
# GoRoute
To configure a GoRoute, a path template and builder must be provided. Specify a
path template to handle by providing a `path` parameter, and a builder by
providing either the `builder` or `pageBuilder` parameter:
```dart
GoRoute(
path: '/users/:userId',
builder: (context, state) => const UserScreen(),
),
```
To navigate to this route, use
[go()](https://pub.dev/documentation/go_router/latest/go_router/GoRouter/go.html).
To learn more about how navigation works, visit the
[Navigation](https://pub.dev/documentation/go_router/latest/topics/Navigation-topic.html)
topic.
# Parameters
To specify a path parameter, prefix a path segment with a `:` character,
followed by a unique name, for example, `:userId`. You can access the value of
the parameter by accessing it through the [GoRouterState][] object provided to
the builder callback:
```dart
GoRoute(
path: '/users/:userId',
builder: (context, state) => const UserScreen(id: state.pathParameters['userId']),
),
```
Similarly, to access a [query
string](https://en.wikipedia.org/wiki/Query_string) parameter (the part of URL
after the `?`), use [GoRouterState][]. For example, a URL path such as
`/users?filter=admins` can read the `filter` parameter:
```dart
GoRoute(
path: '/users',
builder: (context, state) => const UsersScreen(filter: state.queryParameters['filter']),
),
```
# Child routes
A matched route can result in more than one screen being displayed on a
Navigator. This is equivalent to calling `push()`, where a new screen is
displayed above the previous screen with a transition animation, and with an
in-app back button in the `AppBar` widget, if it is used.
To display a screen on top of another, add a child route by adding it to the
parent route's `routes` list:
```dart
GoRoute(
path: '/',
builder: (context, state) {
return HomeScreen();
},
routes: [
GoRoute(
path: 'details',
builder: (context, state) {
return DetailsScreen();
},
),
],
)
```
# Nested navigation
Some apps display destinations in a subsection of the screen, for example, an
app using a BottomNavigationBar that stays on-screen when navigating between
destinations.
To add an additional Navigator, use [ShellRoute][] and provide a builder that returns a widget:
```dart
ShellRoute(
builder:
(BuildContext context, GoRouterState state, Widget child) {
return Scaffold(
body: child,
/* ... */
bottomNavigationBar: BottomNavigationBar(
/* ... */
),
);
},
routes: <RouteBase>[
GoRoute(
path: 'details',
builder: (BuildContext context, GoRouterState state) {
return const DetailsScreen();
},
),
],
),
```
The `child` widget is a Navigator configured to display the matching sub-routes.
For more details, see the [ShellRoute API
documentation](https://pub.dev/documentation/go_router/latest/go_router/ShellRoute-class.html).
For a complete example, see the [ShellRoute
sample](https://github.com/flutter/packages/tree/main/packages/go_router/example/lib/shell_route.dart)
in the example/ directory.
# Initial location
The initial location is shown when the app first opens and there is no deep link
provided by the platform. To specify the initial location, provide the
`initialLocation` parameter to the
GoRouter constructor:
```dart
GoRouter(
initialLocation: '/details',
/* ... */
);
```
# Logging
To enable log output, enable the `debugLogDiagnostics` parameter:
```dart
final _router = GoRouter(
routes: [/* ... */],
debugLogDiagnostics: true,
);
```
[GoRouter]: https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html
[GoRoute]: https://pub.dev/documentation/go_router/latest/go_router/GoRoute-class.html
[GoRouterState]: https://pub.dev/documentation/go_router/latest/go_router/GoRouterState-class.html
[ShellRoute]: https://pub.dev/documentation/go_router/latest/go_router/ShellRoute-class.html