Create a GoRouter configuration by calling the GoRouter constructor and providing list of GoRoute objects:
GoRouter( routes: [ GoRoute( path: '/', builder: (context, state) => const Page1Screen(), ), GoRoute( path: '/page2', builder: (context, state) => const Page2Screen(), ), ], );
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:
GoRoute( path: '/users/:userId', builder: (context, state) => const UserScreen(), ),
To navigate to this route, use go(). To learn more about how navigation, visit the Navigation topic.
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:
GoRoute( path: '/users/:userId', builder: (context, state) => const UserScreen(id: state.pathParameters['userId']), ),
Similarly, to access a 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:
GoRoute( path: '/users', builder: (context, state) => const UsersScreen(filter: state.queryParameters['filter']), ),
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:
GoRoute( path: '/', builder: (context, state) { return HomeScreen(); }, routes: [ GoRoute( path: 'details', builder: (context, state) { return DetailsScreen(); }, ), ], )
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:
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. For a complete example, see the ShellRoute sample in the example/ directory.
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:
GoRouter( initialLocation: '/details', /* ... */ );
To enable log output, enable the debugLogDiagnostics
parameter:
final _router = GoRouter( routes: [/* ... */], debugLogDiagnostics: true, );