Nested navigation in Flutter

Introduction

Nested navigation helps you manage multiple screens inside a part of your app separately. It keeps navigation organized and easy to control.

When you have tabs and each tab has its own set of screens.

When you want to keep navigation inside a section without affecting the whole app.

When you want to go back only inside a part of your app, not the entire app.

When you want to reuse a navigation flow inside different parts of your app.

Syntax

Flutter

Navigator(
  key: navigatorKey,
  onGenerateRoute: (RouteSettings settings) {
    return MaterialPageRoute(
      builder: (context) => YourScreen(),
    );
  },
)

Use a unique GlobalKey to control the nested navigator.

onGenerateRoute defines how to build screens inside the nested navigator.

Examples

This example shows a nested navigator with two routes: home and details inside a tab.

Flutter

Navigator(
  key: _tabNavigatorKey,
  onGenerateRoute: (settings) {
    if (settings.name == '/') {
      return MaterialPageRoute(builder: (_) => TabHomeScreen());
    } else if (settings.name == '/details') {
      return MaterialPageRoute(builder: (_) => TabDetailsScreen());
    }
    return null;
  },
)

Here we create a key to control the nested navigator and define a single screen route.

Flutter

final GlobalKey<NavigatorState> _nestedKey = GlobalKey<NavigatorState>();

Navigator(
  key: _nestedKey,
  onGenerateRoute: (settings) => MaterialPageRoute(builder: (_) => NestedScreen()),
)

Sample App

This app shows a main screen with a nested navigator inside the body. The nested navigator starts at NestedHome with a button. Pressing the button navigates inside the nested navigator to NestedDetails. The main app bar stays the same.

Flutter

import 'package:flutter/material.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: MainScreen(),
    );
  }
}

class MainScreen extends StatefulWidget {
  @override
  State<MainScreen> createState() => _MainScreenState();
}

class _MainScreenState extends State<MainScreen> {
  final GlobalKey<NavigatorState> _nestedNavigatorKey = GlobalKey<NavigatorState>();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Nested Navigation Example')),
      body: Navigator(
        key: _nestedNavigatorKey,
        onGenerateRoute: (settings) {
          if (settings.name == '/') {
            return MaterialPageRoute(builder: (_) => NestedHome(onNext: () {
              _nestedNavigatorKey.currentState?.pushNamed('/details');
            }));
          } else if (settings.name == '/details') {
            return MaterialPageRoute(builder: (_) => NestedDetails());
          }
          return null;
        },
      ),
    );
  }
}

class NestedHome extends StatelessWidget {
  final VoidCallback onNext;
  NestedHome({required this.onNext});

  @override
  Widget build(BuildContext context) {
    return Center(
      child: ElevatedButton(
        onPressed: onNext,
        child: Text('Go to Details'),
      ),
    );
  }
}

class NestedDetails extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Center(
      child: Text('Details Screen'),
    );
  }
}

Important Notes

Each nested navigator needs its own GlobalKey to manage its navigation stack.

Nested navigation keeps the main app navigation separate and clean.

Use nested navigation especially when you have tabs or sections with their own screens.

Summary

Nested navigation lets you manage screens inside a part of your app separately.

Use a Navigator widget with a unique key and onGenerateRoute inside your widget tree.

This helps keep navigation organized and user-friendly.