Implementing Navigation and Routing in Flutter

Core Concepts
Implementing Imperative Navigation
Implementing Declarative Navigation
Implementing Nested Navigation
Workflows
Examples

Core Concepts

Routes: In Flutter, screens and pages are referred to as routes. A route is simply a widget. This is equivalent to an
```
Activity
```
in Android or a
```
ViewController
```
in iOS.
Navigator vs. Router:
- Use
```
Navigator
```
  (Imperative) for small applications without complex deep linking requirements. It manages a stack of
```
Route
```
  objects.
- Use
```
Router
```
  (Declarative) for applications with advanced navigation, web URL synchronization, and specific deep linking requirements.
Deep Linking: Allows an app to open directly to a specific location based on a URL. Supported on iOS, Android, and Web. Web requires no additional setup.
Named Routes: Avoid using named routes (
```
MaterialApp.routes
```
and
```
Navigator.pushNamed
```
) for most applications. They have rigid deep linking behavior and do not support the browser forward button. Use a routing package like
```
go_router
```
instead.

Implementing Imperative Navigation

Use the

Navigator

widget to push and pop routes using platform-specific transition animations (

MaterialPageRoute

CupertinoPageRoute

Pushing and Popping

Navigate to a new route using
```
Navigator.push(context, route)
```
.
Return to the previous route using
```
Navigator.pop(context)
```
.
Use
```
Navigator.pushReplacement()
```
to replace the current route, or
```
Navigator.pushAndRemoveUntil()
```
to clear the stack based on a condition.

Passing and Returning Data

Sending Data: Pass data directly into the constructor of the destination widget. Alternatively, pass data via the
```
settings: RouteSettings(arguments: data)
```
parameter of the
```
PageRoute
```
and extract it using
```
ModalRoute.of(context)!.settings.arguments
```
.
Returning Data: Pass the return value to the
```
pop
```
method:
```
Navigator.pop(context, resultData)
```
. Await the result on the pushing side:
```
final result = await Navigator.push(...)
```
.

Implementing Declarative Navigation

For apps requiring deep linking, web URL support, or complex routing, implement the

Router

API via a declarative routing package like

go_router

Switch from
```
MaterialApp
```
to
```
MaterialApp.router
```
.
Define a router configuration that parses route paths and configures the
```
Navigator
```
automatically.
Navigate using package-specific APIs (e.g.,
```
context.go('/path')
```
).
Page-backed vs. Pageless Routes: Declarative routes are page-backed (deep-linkable). Imperative pushes (e.g., dialogs, bottom sheets) are pageless. Removing a page-backed route automatically removes all subsequent pageless routes.

Implementing Nested Navigation

Implement nested navigation to manage a sub-flow of screens (e.g., a multi-step setup process or persistent bottom navigation tabs) independently from the top-level global navigator.

Instantiate a new
```
Navigator
```
widget inside the host widget.
Assign a
```
GlobalKey<NavigatorState>
```
to the nested
```
Navigator
```
to control it programmatically.
Implement the
```
onGenerateRoute
```
callback within the nested
```
Navigator
```
to resolve sub-routes.
Intercept hardware back button presses using
```
PopScope
```
to prevent the top-level navigator from popping the entire nested flow prematurely.

Workflows

Workflow: Standard Screen Transition

Copy this checklist to track progress when implementing a basic screen transition:

Create the destination widget (Route).
Define required data parameters in the destination widget's constructor.
Implement
```
Navigator.push()
```
in the source widget.
Wrap the destination widget in a
```
MaterialPageRoute
```
or
```
CupertinoPageRoute
```
.
Implement
```
Navigator.pop()
```
in the destination widget to return.

Workflow: Implementing Deep-Linkable Routing

Use this conditional workflow when setting up app-wide routing:

If the app is simple and requires no deep linking:
- Use standard
```
MaterialApp
```
  and
```
Navigator.push()
```
  .
If the app requires deep linking, web support, or complex flows:
- Add the
```
go_router
```
  package.
- Change
```
MaterialApp
```
  to
```
MaterialApp.router
```
  .
- Define the
```
GoRouter
```
  configuration with all top-level routes.
- Replace
```
Navigator.push()
```
  with
```
context.go()
```
  or
```
context.push()
```
  .

Workflow: Creating a Nested Navigation Flow

Run this workflow when building a multi-step sub-flow (e.g., IoT device setup):

Define string constants for the nested route paths.
Create a
```
GlobalKey<NavigatorState>
```
in the host widget's state.
Return a
```
Navigator
```
widget in the host's
```
build
```
method, passing the key.
Implement
```
onGenerateRoute
```
in the nested
```
Navigator
```
to map string paths to specific step widgets.
Wrap the host
```
Scaffold
```
in a
```
PopScope
```
to handle back-button interceptions (e.g., prompting "Are you sure you want to exit setup?").
Use
```
navigatorKey.currentState!.pushNamed()
```
to advance steps within the flow.

Examples

Example: Passing Data via Constructor (Imperative)

dart

// 1. Define the data model
class Todo {
  final String title;
  final String description;
  const Todo(this.title, this.description);
}

// 2. Source Screen
class TodosScreen extends StatelessWidget {
  final List<Todo> todos;
  const TodosScreen({super.key, required this.todos});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Todos')),
      body: ListView.builder(
        itemCount: todos.length,
        itemBuilder: (context, index) {
          return ListTile(
            title: Text(todos[index].title),
            onTap: () {
              // Push and pass data via constructor
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => DetailScreen(todo: todos[index]),
                ),
              );
            },
          );
        },
      ),
    );
  }
}

// 3. Destination Screen
class DetailScreen extends StatelessWidget {
  final Todo todo;
  const DetailScreen({super.key, required this.todo});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(todo.title)),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Text(todo.description),
      ),
    );
  }
}

Example: Nested Navigation Flow