Flutter Go Router Push vs Go: Navigation Stack and Web URL Behavior Explained

Use context.go() to replace the current route and update the URL without adding a browser history entry, and use context.push() to stack a new route on top while adding a history entry that supports the back button.

The go_router package in the flutter/flutter repository provides declarative routing for Flutter applications, but choosing between push and go methods significantly impacts how navigation history behaves—especially on web platforms where URL management is critical.

Understanding the Core Difference Between Push and Go

The go_router library exposes two primary navigation methods through BuildContext extensions. While both update the visible screen and URL, they manipulate the navigation stack differently:

Method Navigation Stack Effect Browser URL on Web Typical Use-Case
context.go(String location) Replaces the current route – the new route becomes the top of the stack and the previous route is removed. Updates the browser's address bar to the new location without adding a new entry to the history (a replace navigation). When you want to move to a different screen and you don't need a back-navigation (e.g., after a login flow, deep-link handling, or redirect).
context.push(String location) Adds a new route on top of the existing stack – the previous route stays beneath it. Adds a new entry to the browser's history, so the address bar changes and the user can press the back button to return. When you want a forward navigation that the user can reverse (e.g., navigating to a details page from a list).

How Push and Go Affect Web URLs and Browser History

On web platforms, the distinction between these methods determines how the browser's history stack behaves and whether the back button functions as users expect.

The Go Method: Replace Navigation

When you call context.go('/new-route'), the implementation invokes Navigator.replace internally through the GoRouterDelegate. This triggers Router.neglect, which updates the URL synchronously without creating a new history entry.

In go_router.dart, the go() method calls _routerDelegate.replaceLocation(), which ultimately results in:

  • No animation between pages (immediate replacement)
  • No history entry added to the browser stack
  • URL update visible in the address bar

This behavior is essential for authentication flows where you want to remove the login page from history after successful authentication, preventing users from navigating back to it using the browser back button.

The Push Method: Stack Navigation

Conversely, context.push('/new-route') utilizes Navigator.push through _routerDelegate.pushLocation(). This approach:

  • Adds a history entry to the browser's stack
  • Triggers standard page-transition animations
  • Preserves the underlying route in the navigation stack

According to the source code in router_delegate.dart, the push operation creates a new RouteMatch that gets appended to the existing stack, allowing the browser back button to pop this route and return to the previous location.

Implementation Details in the Go Router Source Code

The behavioral differences stem from distinct implementation paths within the go_router package source files.

In go_router.dart, the extension methods on BuildContext provide the public API:

// From go_router.dart
void go(String location, {Object? extra}) {
  GoRouter.of(this).go(location, extra: extra);
}

void push(String location, {Object? extra}) {
  GoRouter.of(this).push(location, extra: extra);
}

These delegate to the GoRouter instance methods, which interact with GoRouterDelegate defined in router_delegate.dart:

  • go() invokes replaceLocation() → calls setNewRoutePath() with Router.neglect → results in Navigator.replace
  • push() invokes pushLocation() → creates new RouteMatch → calls Navigator.push

The RouteMatch class in route_match.dart represents the parsed URL segments and parameters, while go_router_state.dart maintains the state object passed during navigation transitions.

Practical Code Examples

Basic Navigation with Context Extensions

The most common pattern uses the extension methods on BuildContext:

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

class DashboardScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Dashboard')),
      body: Column(
        children: [
          // Replace navigation - removes dashboard from history
          ElevatedButton(
            onPressed: () => context.go('/home'),
            child: Text('Go to Home (Replace)'),
          ),
          
          // Stack navigation - preserves dashboard in history
          ElevatedButton(
            onPressed: () => context.push('/settings'),
            child: Text('Push Settings (Add to Stack)'),
          ),
        ],
      ),
    );
  }
}

Using GoRouter Directly

When accessing the router outside of widget build contexts (e.g., in business logic or providers):

final router = GoRouter.of(context);

// Replace current location
router.go('/profile');

// Add new location to stack
router.push('/profile/details');

Platform-Specific Navigation Patterns

Web applications often require different navigation strategies than mobile apps:

import 'package:flutter/foundation.dart';

void navigateToSearch(BuildContext context) {
  if (kIsWeb) {
    // On web, use push to enable browser back button functionality
    context.push('/search');
  } else {
    // On mobile, go() provides cleaner stack management
    context.go('/search');
  }
}

When to Use Go vs Push

Choosing the correct method depends on your navigation requirements:

Use context.go() when:

  • Implementing authentication flows (remove login page after success)
  • Handling deep links that should replace the current state
  • Performing redirects that shouldn't appear in history
  • Building single-page navigation patterns on mobile where back buttons aren't needed

Use context.push() when:

  • Navigating to detail pages from master lists
  • Creating drill-down navigation where users expect to return
  • Building web applications where browser back button support is essential
  • Implementing modal or auxiliary flows that should preserve the underlying page

Summary

  • context.go() replaces the current route and updates the URL without adding a browser history entry, making it ideal for redirects and authentication flows.
  • context.push() adds a new route to the navigation stack and creates a browser history entry, enabling standard back-button functionality on web and mobile.
  • The implementation in go_router.dart delegates to GoRouterDelegate methods: replaceLocation() for go() and pushLocation() for push().
  • On web platforms, go() triggers Router.neglect and Navigator.replace, while push() uses standard Navigator.push with full history management.

Frequently Asked Questions

What happens to the browser back button when using context.go() in Flutter web?

When you use context.go() on web platforms, the browser back button will not return to the page that called go(). Instead, it navigates to the page that was active before the current one, because go() replaces the current history entry rather than pushing a new one. This behavior is implemented through Router.neglect in the go_router delegate, making it ideal for login flows where you want to prevent users from returning to authentication screens.

Can I use push and go interchangeably in mobile apps?

While both methods will display the target page on mobile devices, they create different navigation stack behaviors that affect the system back button and gesture navigation. Using context.go() removes the current route from the stack, meaning the system back button (Android) or swipe gesture (iOS) will exit the app or jump to the previous route in history, not the immediate predecessor screen. Use context.push() when you want standard mobile back-navigation behavior that returns to the previous screen.

How do go and push handle URL parameters and extra data?

Both methods accept identical parameters: a String location (the URL path) and an optional Object? extra payload for passing data between routes. In go_router.dart, both go() and push() forward these arguments to their respective delegate methods (replaceLocation and pushLocation), which parse the location string against defined GoRoute patterns and preserve the extra data in the resulting RouteMatch objects. This means you can pass complex objects with either method using the extra parameter without serialization concerns.

Why does context.go() not show page transition animations?

The go() method uses Navigator.replace internally rather than Navigator.push, which bypasses the standard route transition animation system. In router_delegate.dart, the replaceLocation implementation calls setNewRoutePath with Router.neglect, effectively swapping the current page widget without the push/pop animation sequence. If you need visual transitions while replacing routes, consider using push() followed by removeRoute logic, or implement custom transition handling in your GoRoute configuration using the pageBuilder parameter.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"

Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →