Navigator

The Key Concepts

Navand has its own navigator that uses the browser's History API. It has two main entities:

• Routes: They are entities like typical routes and have a corresponding path in the URL. They are generally accessible in the application regardless of the users' actions (except for the ones that need user authentication, of course).
• Modals: They are entities like dialogs, navigation drawers, bottom sheets, etc. that rely on users' actions or the flow of the application. They don't have a corresponding path in the URL because they must be shown to the user in specific conditions and in response to their actions.

It also has the following concepts:

• Only a single instance of Navigator should be created in the app.
• Because modals should be accessible only through users' actions or the flow of the application, the browser's forward button should be disabled (in the same way that most modern native apps don't have one).
• When the browser's back button is pressed or Navigator.pop is called, the latest modal, and if there are no modals left, the latest route should be popped.

Features

• Modals (that behave the same as native modals)

• Nested routes

• Redirects

• 3 types of routes

  • Wildcard (*)
  • Dynamic (:<parameterName>)
  • Static (<segment-name>)

  NOTE: You should follow the exact naming conventions mentioned above. Route paths such as :lat-:long, comment-:id, and first/second/third are not supported. Look at the following examples for nested routes.

Examples

First, you have to define your Navigator instance containing all the routes your app has. Then, you can call the navigation methods statically available on Navigator through your app.

Defining Routes

You can define routes like this:

Navigator(
  routes: [
    // Redirects are supported through `redirector`.
    Route(path: '', redirector: (final context, final state) => '/home'),
    Route(
      path: 'home',
      builder: (final context, final state) => const Text('Home'),
      // Routes can be nested.
      routes: [
        Route(
          path: 'notifications',
          builder: (final context, final state) => const Text('Notifications'),
          routes: [
            Route(
              // Routes can be defined as dynamic.
              path: ':id',
              builder: (final context, final state) =>
                  Text('Notification ID: ${state.params['id']}'),
            ),
          ],
        ),
      ],
    ),
    Route(
      path: 'about',
      builder: (final context, final state) => const Text('About'),
    ),
    Route(
      // Wildcards can be used in different cases like "Not Found" pages.
      path: '*',
      builder: (final context, final state) => const Text('Not Found'),
    ),
  ],
);

Navigating

4 static methods are available on Navigator that can be used to navigate through your app:

// Popping the latest modal or the latest route.
await Navigator.pop();

// Pushing a new route.
await Navigator.pushRoute('/about');

// Replacing the current route.
await Navigator.replaceRoute('/about');

// Pushing a new modal
await Navigator.pushModal(
  onPop: () {
    // Closing the modal in the UI.
  },
);