Learn

Choose the exact stack operation

Pick push, replacement, removal, pop, or branch operations from the Back behavior your screen requires.

v1.1.0Beginner

Choose the exact stack operation

Start from the Back button behavior you need. Ark Navigation does not hide that choice behind one generic method.

Desired result	Operation
Add Detail above List	`push`
Replace Login with Home	`replaceTop`
Update parameters without ending the current Entry	`reconfigureTop`
Set the complete signed-in stack	`replaceAll` or `setStack`
Open Receipt and remove Checkout steps	`pushAndRemoveUntil`
Replace everything above a known shell	`replaceTail`
Return one page with a value	`pop`
Pop back to a known Route or Entry	`popUntil`
Remove one exact background Entry	`remove`
Switch a retained tab	`activateBranch`
Clear a tab and all nested stacks	`resetBranch`

Push and receive a result

dart

final ticket = navigation.push<Address?>(
  const AddressPickerDestination(),
);

final commit = await ticket.committed;
switch (commit) {
  case NavigationCommitted():
    break;
  case NavigationRejected(:final reason):
    debugPrint('Address picker was denied: $reason');
    return;
  case NavigationFailed(:final error):
    debugPrint('Navigation failed: $error');
    return;
  case NavigationNoChange(:final reason):
    debugPrint('Nothing changed: $reason');
    return;
}

final completion = await ticket.completed;
if (completion case NavigationPopped<Address?>(:final result)) {
  selectedAddress = result;
}

committed answers whether the Entry was added. completed answers how that Entry eventually left the stack. Keeping them separate prevents a Guard denial from looking like a returned null result.

Reset after authentication

dart

await navigation.replaceAll(<NavigationTarget<Object?>>[
  const NavigationTarget<Object?>(destination: HomeDestination()),
  const NavigationTarget<Object?>(destination: AccountDestination()),
]);

After this commit, Back cannot return to Login because Login is no longer in the stack.

Pop to a known route

dart

await navigation.popUntil(
  anchor: const NavigationRouteIdMatcher(NavigationRouteId('cart')),
);

Use NavigationEntryIdMatcher when several copies of the same route can exist and you need one exact occurrence.

Browser history is explicit too

Every operation accepts historyMode. Use push for a new browser Back step and replace for corrections or redirects that should not create one:

dart

navigation.replaceTop<void>(
  const HomeDestination(),
  historyMode: NavigationHistoryMode.replace,
);