Flutter GoRouter Extension

A Flutter package that extends go_router with Android-style navigation behaviors.

Features

  • isCurrent: Returns true if the current BuildContext belongs to the top-most route in the navigation stack.
  • pushAndRemoveUntil: Simulates Android's FLAG_ACTIVITY_CLEAR_TOP | FLAG_ACTIVITY_NEW_TASK behavior
  • popUntil: Pop routes until a specific route is reached, preserving the existing instance
  • popToRoot: Pop all routes until the root route is reached.
  • Supports dynamic route parameters (e.g., /user/:id)
  • Supports wildcard routes (e.g., /files/*)

Installation

Add this to your pubspec.yaml:

dependencies:
  flutter_go_router_extension: ^1.3.1

Usage

isCurrent

Returns true if the current BuildContext belongs to the top-most route in the navigation stack.

// In your widget
if (context.isCurrent) {
  // Do something only if this is the active screen
}

popToRoot

Pops all routes from the navigator stack until the root route (/) is reached.

// In your widget
ElevatedButton(
  onPressed: () {
    context.popToRoot();
  },
  child: Text('Pop to Root'),
)

pushAndRemoveUntil

When navigating to a page that already exists in the stack, it clears all pages above and including that page, then pushes a new instance of the target page.

popUntil

Pops routes from the stack until a route matching the target URL is found, preserving the existing instance of that route (state, scroll position, and parameters are all retained).

Unlike pushAndRemoveUntil, this method does not create a new page instance—it simply removes the routes above the matching one.

import 'package:flutter_go_router_extension/flutter_go_router_extension.dart';

// In your widget
ElevatedButton(
  onPressed: () {
    context.popUntil('/user/123');
  },
  child: Text('Back to User'),
)

Comparison with pushAndRemoveUntil:

Method Matching route instance
pushAndRemoveUntil(url) New instance (state reset)
popUntil(url) Existing instance (state preserved)

If the target URL is not found in the stack, the method does nothing.

import 'package:flutter_go_router_extension/flutter_go_router_extension.dart';

// In your widget
ElevatedButton(
  onPressed: () {
    context.pushAndRemoveUntil('/user/123');
  },
  child: Text('Go to User'),
)

Example

If the original stack is:

/home -> /user/123 -> /user/123/posts -> /comments

And you call:

context.pushAndRemoveUntil('/user/123');

Processing steps:

  1. Route /user/:id converts to RegExp: ^/user/[^/]+$
  2. Check /comments - No match, remove
  3. Check /user/123/posts - No match, remove
  4. Check /user/123 - Match found

Resulting stack:

/home -> /user/123 (new instance)

How It Works

  1. Path to Regex Conversion: Dynamic parameters (:param) are converted to [^/]+, wildcards (*) to .*
  2. Stack Traversal: Iterates from the top of the navigation stack
  3. Match & Clear: When a matching route is found, all routes above it (including itself) are removed
  4. Push New Instance: A fresh instance of the target page is pushed onto the stack

Requirements

  • Flutter SDK
  • go_router: ^14.0.0 or higher

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

Libraries

flutter_go_router_extension