blob: af4751331bcb307a323731a23291903b7591b459 [file] [log] [blame] [view]
# go_router, A Declarative Routing Package for Flutter
This package builds on top of the Flutter framework's Router API and provides
convenient url-based APIs to navigate between different screens. You can
define your own url patterns, navigating to different url, handle deep and
dynamic linking, and a number of other navigation-related scenarios.
## Getting Started
Follow the [package install instructions](https://pub.dev/packages/go_router/install),
and you can start using go_router in your code:
```dart
class App extends StatelessWidget {
App({Key? key}) : super(key: key);
@override
Widget build(BuildContext context) => MaterialApp.router(
routeInformationProvider: _router.routeInformationProvider,
routeInformationParser: _router.routeInformationParser,
routerDelegate: _router.routerDelegate,
title: 'GoRouter Example',
);
final GoRouter _router = GoRouter(
routes: <GoRoute>[
GoRoute(
path: '/',
builder: (BuildContext context, GoRouterState state) => const Page1Screen(),
),
GoRoute(
path: '/page2',
builder: (BuildContext context, GoRouterState state) => const Page2Screen(),
),
],
);
}
```
## Define Routes
go_router is governed by a set of routes which are specify as part of the
[GoRouter](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
constructor:
```dart
GoRouter(
routes: [
GoRoute(
path: '/',
builder: (context, state) => const Page1Screen(),
),
GoRoute(
path: '/page2',
builder: (context, state) => const Page2Screen(),
),
],
);
```
It defined two routes, `/` and `/page2`. Each route path will be matched against
the location to which the user is navigating. The path will be matched in a
case-insensitive way, although the case for parameters will be preserved. If
there are multiple route matches, the <b>first</b> match in the list takes priority
over the others.
In addition to the path, each route will typically have a [builder](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/builder.html)
function that is responsible for building the `Widget` that is to take up the
entire screen of the app. The default transition is used between pages
depending on the app at the top of its widget tree, e.g. the use of `MaterialApp`
will cause go_router to use the `MaterialPage` transitions. Consider using
[pageBuilder](https://pub.dev/documentation/go_router/latest/go_router/GoRoute/pageBuilder.html)
for custom `Page` class.
## Initalization
Once a [GoRouter](https://pub.dev/documentation/go_router/latest/go_router/GoRouter-class.html)
object is created, it can be used to initialize `MaterialApp` or `CupertinoApp`.
```dart
final GoRouter _router = GoRouter(..);
MaterialApp.router(
routeInformationProvider: _router.routeInformationProvider,
routeInformationParser: _router.routeInformationParser,
routerDelegate: _router.routerDelegate,
);
```
## Error handling
By default, go_router comes with default error screens for both `MaterialApp` and
`CupertinoApp` as well as a default error screen in the case that none is used.
Once can also replace the default error screen by using the [errorBuilder](https://pub.dev/documentation/go_router/latest/go_router/GoRouter/GoRouter.html):
```dart
GoRouter(
...
errorBuilder: (context, state) => ErrorScreen(state.error),
);
```
## Navigation
To navigate between routes, use the [GoRouter.go](https://pub.dev/documentation/go_router/latest/go_router/GoRouter/go.html) method:
```dart
onTap: () => GoRouter.of(context).go('/page2')
```
go_router also provides a simplified means of navigation using Dart extension
methods:
```dart
onTap: () => context.go('/page2')
```
<br>
### Still not sure how to proceed? See [examples](https://github.com/flutter/packages/tree/main/packages/go_router/example) for complete runnable examples or visit [API documentation](https://pub.dev/documentation/go_router/latest/go_router/go_router-library.html)
## Migration guides
- [Migrating to 2.0](https://flutter.dev/go/go-router-v2-breaking-changes)
- [Migrating to 2.5](https://flutter.dev/go/go-router-v2-5-breaking-changes)
- [Migrating to 3.0](https://flutter.dev/go/go-router-v3-breaking-changes)
- [Migrating to 4.0](https://flutter.dev/go/go-router-v4-breaking-changes)
## Changelog
See the [Changelog](https://github.com/flutter/packages/blob/main/packages/go_router/CHANGELOG.md)
for a list of new features and breaking changes.