Persistent Back Button
Component Detail
Description
A back control that appears on every screen that is not a root tab destination, providing an explicit tap-based way to navigate up the stack without relying on platform swipe-back gestures. Supports both AppBar integration and custom floating placements for full-screen modal routes.
persistent-back-button
Summaries
The Persistent Back Button guarantees that users can always navigate backward through the application using a clearly visible, tap-based control — without relying on platform-specific swipe gestures that are inaccessible to motor-impaired users and inconsistent across device manufacturers. By providing an explicit, labeled back control on every non-root screen, the product reduces user disorientation, supports the broadest possible audience including assistive technology users, and meets WCAG navigation standards. This shared control directly contributes to a polished, professional navigation experience that builds user confidence and reduces abandonment caused by navigation dead-ends or confusing interaction patterns.
This low-complexity shared component has no runtime dependencies, making it a low-risk early deliverable that should be implemented before feature screens are built, as each non-root screen will integrate it. Testing must cover GoRouter navigation stack integrity confirming canNavigateBack returns correct values at all route depths, semantic tooltip accuracy for screen readers on both iOS and Android, correct rendering in both AppBar leading and floating placements for full-screen modal routes, and validation that swipe-back is suppressed as a sole mechanism where required. Its wide integration surface means any behavioral change post-integration requires regression testing across all navigable screens in the application, warranting strict change control.
The Persistent Back Button integrates with GoRouter's navigation context, using GoRouter.of(context).canPop() or equivalent for canNavigateBack(context) and calling context.pop() via navigateBack(context) on tap. buildBackButton(context, label) supports both AppBar leading widget placement and free-floating Widget placement for full-screen modal routes. overridePlatformSwipeBack(disabled) wraps the route with PopScope(canPop: false) to suppress the platform swipe-back gesture on routes where tap-only dismissal is required. A Semantics widget with a tooltip and explicit button role ensures VoiceOver and TalkBack announce the navigation action and destination correctly via announceNavigation(context, destination).
The component is fully stateless — no internal state, no side effects — safe to instantiate anywhere in the widget tree.
Responsibilities
- Display a labelled back button on all non-root screens
- Pop the current route on tap using GoRouter navigation
- Disable swipe-back as the sole dismissal mechanism on platform routes
- Provide semantic tooltip for screen reader announcement
Interfaces
buildBackButton(context, label)
navigateBack(context)
canNavigateBack(context)
overridePlatformSwipeBack(disabled)
announceNavigation(context, destination)