Navigation Stack Previewer

A Flutter package that provides a visual preview of your app's navigation stack. Simply swipe from the screen edge to see screenshots of your previous screens and navigate back instantly.

Demo Video

Screenshots

Features

• Visual History: See real screenshots of previous screens in your navigation stack.
• Easy Navigation: Tap on any screenshot or the "Preview" button to jump directly back to that screen.
• Multiple Layouts: Choose between Carousel and List layouts.
• Flexible Positioning: Open the panel from the Top or Bottom of the screen.
• Auto-Detection: Automatically detects push, pushReplacement, and pop operations.
• Enlarged Preview: View high-resolution screenshots in a full-screen mode directly within the panel.
• Global Integration: Set it up once and it works across your entire app.
• Customizable Appearance: Change colors, titles, and animations via a unified config object.
• Filtering: Hide specific screens from the previewer using RouteSettings.

Getting started

Add the package to your pubspec.yaml:

dependencies:
  navigation_stack_previewer: ^0.0.4

Usage

1. Initialize the library

Call initNavHistory() in your main() function:

import 'package:navigation_stack_previewer/navigation_stack_previewer.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initNavHistory();
  runApp(const MyApp());
}

2. Configure MaterialApp

Add the NavigationStackObserver and wrap your app with NavigationStackPreviewer:

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [
        NavigationStackObserver(),
      ],
      builder: (context, child) {
        return NavigationStackPreviewer(
          config: const StackPreviewConfig(
            layout: StackPreviewLayout.carousel,
            position: StackPreviewPosition.top,
            animationDuration: Duration(milliseconds: 500),
            animationCurve: Curves.fastOutSlowIn,
            primaryColor: Colors.red,
            backgroundColor: Colors.white,
            maxRoutes: 15,
            pixelRatio: 0.5,
            panelHeight: 400,
            enlargedPanelHeight: 800,
          ),
          child: child!,
        );
      },
      home: const MyHomePage(),
    );
  }
}

3. Swipe and Navigate!

• Swipe from the configured edge (Top or Bottom) to open the panel.
• Tap a screenshot to navigate back to it.
• Tap the Eye Icon to see an enlarged full-screen view of the screenshot.
• Tap the X to remove a specific screen from the stack.

Advanced Customization

Hiding Screens

Exclude specific screens by passing preview: false in RouteSettings:

Navigator.of(context).push(
  MaterialPageRoute(
    builder: (_) => const SecretPage(),
    settings: const RouteSettings(
      arguments: {'preview': false},
    ),
  ),
);

Configuration Options (StackPreviewConfig)

Parameter	Type	Default	Description
layout	StackPreviewLayout	carousel	carousel or list.
position	StackPreviewPosition	top	top or bottom.
primaryColor	Color	Color(0xFFc03463)	Accent color for borders and buttons.
backgroundColor	Color	Colors.white	Panel background color.
panelHeight	double	400.0	Initial height of the history panel.
enlargedPanelHeight	double	800.0	Height when viewing an enlarged screenshot.
maxRoutes	int	5	Max screens to store in history.
pixelRatio	double	0.5	Resolution of captured screenshots.
title	String	'Navigation Stack'	Header text of the panel.

Additional information

This package uses RepaintBoundary to capture screenshots efficiently. It is designed for development and debugging purposes.

Contributions are welcome on the GitHub repository!