What is the purpose of the Navigator class in Flutter?

Overview

The

Navigator

Core Purpose

Navigator serves three main purposes:

1. Manages Screen Stack - Maintains a stack of Route objects representing screens
2. Provides Navigation Methods - Offers APIs like
   textCopy

   push()

   ,
   textCopy

   pop()

   ,
   textCopy

   pushReplacement()

   to control navigation
3. Handles Transitions - Manages platform-specific animations when moving between screens

How Navigator Works

Navigator uses a stack data structure (LIFO - Last In, First Out):

textCopy
┌─────────────────┐
│  Details Screen │ ← Top of stack (current screen)
├─────────────────┤
│  List Screen    │
├─────────────────┤
│  Home Screen    │ ← Bottom of stack (root screen)
└─────────────────┘

Basic Navigation Methods

1. Push - Add Screen to Stack

dartCopy
// Add a new screen on top of the current one
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => DetailScreen()),
);

2. Pop - Remove Current Screen

dartCopy
// Remove the current screen and return to previous one
Navigator.pop(context);

// Pop with a result value
Navigator.pop(context, 'Selected Value');

3. PushNamed - Navigate Using Route Name

dartCopy
// Navigate using predefined route names
Navigator.pushNamed(context, '/details');

// With arguments
Navigator.pushNamed(
  context,
  '/details',
  arguments: {'id': 123, 'title': 'Product'},
);

Advanced Navigation Methods

1. PushReplacement - Replace Current Screen

dartCopy
// Replace current screen without adding to stack
Navigator.pushReplacement(
  context,
  MaterialPageRoute(builder: (context) => HomeScreen()),
);

// Example: After login, replace login screen with home
ElevatedButton(
  onPressed: () async {
    final success = await login();
    if (success) {
      Navigator.pushReplacement(
        context,
        MaterialPageRoute(builder: (context) => HomeScreen()),
      );
    }
  },
  child: Text('Login'),
)

2. PushAndRemoveUntil - Clear Stack and Push

dartCopy
// Clear all previous routes and add new one
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (context) => HomeScreen()),
  (route) => false, // Remove all previous routes
);

// Keep routes until a condition is met
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (context) => ProfileScreen()),
  ModalRoute.withName('/home'), // Keep routes up to /home
);

3. PopUntil - Pop Multiple Screens

dartCopy
// Pop until reaching a specific route
Navigator.popUntil(context, ModalRoute.withName('/home'));

// Pop until condition is met
Navigator.popUntil(context, (route) => route.isFirst);

4. CanPop - Check if Pop is Possible

dartCopy
// Check if there are routes to pop
if (Navigator.canPop(context)) {
  Navigator.pop(context);
} else {
  // Already at root, maybe show exit dialog
  showExitDialog();
}

5. MaybePop - Pop Only if Possible

dartCopy
// Safely pop without checking canPop
await Navigator.maybePop(context);

// With result
await Navigator.maybePop(context, 'result');

Complete Navigation Example

dartCopy
import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Navigator Demo',
      initialRoute: '/',
      routes: {
        '/': (context) => HomeScreen(),
        '/list': (context) => ListScreen(),
        '/details': (context) => DetailScreen(),
      },
    );
  }
}

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Home')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            ElevatedButton(
              onPressed: () {
                // Push to list screen
                Navigator.push(
                  context,
                  MaterialPageRoute(builder: (context) => ListScreen()),
                );
              },
              child: Text('Go to List (Push)'),
            ),
            SizedBox(height: 10),
            ElevatedButton(
              onPressed: () {
                // Push using named route
                Navigator.pushNamed(context, '/list');
              },
              child: Text('Go to List (Named)'),
            ),
          ],
        ),
      ),
    );
  }
}

class ListScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('List')),
      body: ListView.builder(
        itemCount: 10,
        itemBuilder: (context, index) {
          return ListTile(
            title: Text('Item $index'),
            onTap: () async {
              // Navigate to details and wait for result
              final result = await Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => DetailScreen(id: index),
                ),
              );
              
              if (result != null) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Result: $result')),
                );
              }
            },
          );
        },
      ),
    );
  }
}

class DetailScreen extends StatelessWidget {
  final int id;

  const DetailScreen({Key? key, this.id = 0}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Details #$id')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Detail Screen for Item $id'),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: () {
                // Pop with result
                Navigator.pop(context, 'Liked Item $id');
              },
              child: Text('Like and Go Back'),
            ),
            SizedBox(height: 10),
            ElevatedButton(
              onPressed: () {
                // Pop to home screen
                Navigator.popUntil(context, ModalRoute.withName('/'));
              },
              child: Text('Back to Home'),
            ),
            SizedBox(height: 10),
            ElevatedButton(
              onPressed: () {
                // Replace with another screen
                Navigator.pushReplacement(
                  context,
                  MaterialPageRoute(
                    builder: (context) => DetailScreen(id: id + 1),
                  ),
                );
              },
              child: Text('Next Detail'),
            ),
          ],
        ),
      ),
    );
  }
}

Navigator with Custom Transitions

dartCopy
Navigator.push(
  context,
  PageRouteBuilder(
    pageBuilder: (context, animation, secondaryAnimation) => DetailScreen(),
    transitionsBuilder: (context, animation, secondaryAnimation, child) {
      const begin = Offset(1.0, 0.0);
      const end = Offset.zero;
      const curve = Curves.easeInOut;
      
      var tween = Tween(begin: begin, end: end).chain(
        CurveTween(curve: curve),
      );
      
      return SlideTransition(
        position: animation.drive(tween),
        child: child,
      );
    },
  ),
);

Navigator API Overview

push()

pop()

pushNamed()

pushReplacement()

pushAndRemoveUntil()

popUntil()

canPop()

maybePop()

popAndPushNamed()

Two Navigation Styles

Imperative API (Navigator 1.0)

dartCopy
// Direct method calls
Navigator.push(context, route);
Navigator.pop(context);

Declarative API (Navigator 2.0)

dartCopy
// Define pages based on app state
Navigator(
  pages: [
    MaterialPage(child: HomeScreen()),
    if (showDetails)
      MaterialPage(child: DetailScreen()),
  ],
  onPopPage: (route, result) => route.didPop(result),
);

Best Practices

• Use named routes for apps with many screens
• Always check
  textCopy

  canPop()

  before popping to avoid errors
• Use
  textCopy

  pushReplacement()

  after authentication to prevent going back
• Return data with
  textCopy

  pop()

  when collecting user input
• Use
  textCopy

  pushAndRemoveUntil()

  for logout flows
• Implement custom transitions for better UX
• Handle back button properly on Android with
  textCopy

  PopScope

Common Use Cases

Login Flow

dartCopy
// After successful login, don't allow back to login screen
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (context) => HomeScreen()),
  (route) => false,
);

Logout Flow

dartCopy
// Clear all screens and go to login
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (context) => LoginScreen()),
  (route) => false,
);

Multi-step Form

dartCopy
// Step 1 → Step 2 → Step 3 → Success
// On success, go back to home
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (context) => HomeScreen()),
  ModalRoute.withName('/'),
);

Official Documentation

• Navigator Class API
• Flutter Navigation and Routing
• Navigation Cookbook