Gesture Navigation #

Reliable swipe and edge navigation for Flutter, with lifecycle events, declarative route actions, live progress, haptics, and adaptive transitions.

Version 0.1.0 introduces one shared gesture engine for Android and iOS. The package is implemented in Flutter and requires no native permissions or setup.

Features #

• Physical left, right, up, and down swipe recognition
• Optional left, right, top, or bottom edge activation
• Distance, velocity, axis-lock, and progress configuration
• Started, updated, completed, and cancelled lifecycle events
• Push, pop, replace, next, previous, dismiss, and callback actions
• Automatic right-to-left resolution for semantic next/previous actions
• Adaptive Cupertino and Material routes plus custom transitions
• Live built-in or application-defined progress indicators
• Page, tab, and start/end drawer bindings
• Gesture-arena participation for predictable scroll conflicts
• Touch and mouse pointer filtering

Watch the swipe-navigation demo.

Platform support #

The example is continuously validated as an Android release bundle and an iOS Simulator application. Its iOS deployment target is 13.0.

Requirements #

• Flutter 3.41.0 or newer
• Dart 3.4.4 or newer

Installation #

dependencies:
  gesture_navigation: ^0.1.0

Then import the package:

import 'package:gesture_navigation/gesture_navigation.dart';

Quick start #

GestureNavigationRegion recognizes the interaction. A controller can map the completed event directly to navigation behavior.

GestureNavigationRegion(
  config: const GestureNavigationConfig(
    allowedDirections: {
      SwipeDirection.left,
      SwipeDirection.right,
    },
    minimumDistance: 56,
    minimumVelocity: 350,
    progressDistance: 160,
  ),
  controller: GestureNavigationController(
    nextAction: GestureNavigationAction.next(
      pageBuilder: (_) => const DetailsPage(),
      transition: const GestureNavigationTransition.adaptive(),
    ),
    previousAction: const GestureNavigationAction.previous(),
  ),
  indicatorBuilder: (context, event) =>
      GestureNavigationIndicator(event: event),
  child: const Scaffold(
    body: Center(child: Text('Swipe left or right')),
  ),
);

In a left-to-right layout, a physical left swipe runs nextAction and a right swipe runs previousAction. The semantic mapping reverses in a right-to-left layout. Explicit entries in the controller's actions map always use physical directions and take precedence.

Gesture lifecycle #

Use onEvent when the application needs progress or cancellation details, and onNavigation when it only needs completed gestures.

GestureNavigationRegion(
  onEvent: (event) {
    switch (event.phase) {
      case GestureNavigationPhase.started:
      case GestureNavigationPhase.updated:
        debugPrint('Progress: ${event.progress}');
        break;
      case GestureNavigationPhase.ended:
        debugPrint('Completed: ${event.direction}');
        break;
      case GestureNavigationPhase.cancelled:
        debugPrint('Cancelled');
        break;
    }
  },
  child: const YourScreen(),
);

Events include local start/current positions, physical direction, activation edge, velocity, elapsed time, normalized progress, and pointer-device kind.

Edge-only navigation #

A non-empty allowedEdges set requires the pointer to start inside an enabled edge area. Movement must be inward from that edge.

GestureNavigationRegion(
  config: const GestureNavigationConfig(
    allowedDirections: {SwipeDirection.right},
    allowedEdges: {GestureNavigationEdge.left},
    edgeWidth: 24,
    minimumDistance: 56,
  ),
  controller: GestureNavigationController(
    previousAction: const GestureNavigationAction.previous(),
  ),
  child: const YourScreen(),
);

Actions and transitions #

GestureNavigationAction supports:

• push and next
• pop and previous
• replace
• dismiss for routes, dialogs, sheets, and navigator-backed overlays
• callback for application-specific behavior

Generated routes can use adaptive, slide, fade, scale, no-animation, or custom transitions. Actions can also supply route settings, fullscreen-dialog behavior, results, and root-navigator selection.

Application-shell bindings #

GestureNavigationBindings provides reusable actions for page controllers, tab controllers, and keyed scaffolds.

final scaffoldKey = GlobalKey<ScaffoldState>();
final pageController = PageController();

final controller = GestureNavigationController(
  nextAction: GestureNavigationBindings.nextPage(
    controller: pageController,
    itemCount: 4,
    wrap: true,
  ),
  previousAction: GestureNavigationBindings.previousPage(
    controller: pageController,
    itemCount: 4,
    wrap: true,
  ),
  actions: {
    SwipeDirection.down: GestureNavigationBindings.openDrawer(
      scaffoldKey: scaffoldKey,
    ),
    SwipeDirection.up: const GestureNavigationAction.dismiss(),
  },
);

Page and tab bindings support custom curves and duration, optional wrapping, boundary callbacks, and safe handling of unattached page controllers. Drawer bindings can open or close both the start and end drawers.

Progress indicators #

indicatorBuilder receives the current structured event and places its output above the region without intercepting input. The included GestureNavigationIndicator provides an accessible directional arrow and circular progress display. Applications can customize it or return any widget.

Compatibility APIs #

The existing SwipeNavigation and EdgeGesture constructors remain available in 0.1.0 and now use the shared recognition engine. SwipeNavigation retains percentage thresholds and callbacks. EdgeGesture adds completion distance, velocity, and indicator settings while correctly requiring an edge start.

The old SwipeNavigation.transitionType property and createPageTransition helper are deprecated. Use GestureNavigationAction with GestureNavigationTransition for new code.

The package also continues to export PinchZoom, DragReorder, ModalControl, and GestureSettings for compatibility with earlier releases.

When upgrading, use Flutter 3.41.0 or newer. Existing SwipeNavigation callbacks and percentage thresholds continue to work. Edge swipes must now start inside edgeThreshold, and navigation callbacks run only after a gesture completes. New integrations should use GestureNavigationRegion, GestureNavigationController, and GestureNavigationAction.

Running the example #

cd example
flutter pub get
flutter run

The example includes swipe navigation, edge gestures, live indicators, page/drawer bindings, pinch zoom, drag reordering, and modal controls.

Issues and source #

• Repository
• Issue tracker

License #

Apache License 2.0. See the LICENSE.