🧭 Flutter NavKit

A powerful and elegant navigation toolkit for Flutter that simplifies routing with type-safe navigation, automatic route generation, and comprehensive navigation observability.

flutter_navkit 2.0.2 repo 2.0.2

✨ Features

  • 🎯 Type-Safe Navigation - Auto-generated route constants with IDE autocomplete
  • 🔍 Navigation Observer - Built-in tracking with detailed logging and route stack visualization
  • 🚀 Simple Extensions - Clean, intuitive extension methods on BuildContext
  • 📦 Auto Route Generation - Annotate widgets and generate routes automatically
  • 🧭 Custom Transitions - Built-in fade, slide, scale, rotation, and size animations
  • 🎨 Programmatic Routes - Define routes with NavKitGeneratedRoute for full control
  • 🎭 UI Helpers - Show sheets, dialogs, and snackbars with ease
  • 🔄 Stack Management - Check routes, pop multiple screens, navigate safely
  • 🛡️ Error Handling - Built-in error logging with safe navigation fallbacks
  • 📱 Flutter-Native - Works seamlessly with Flutter's navigation system

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flutter_navkit: ^2.0.2

dev_dependencies:
  build_runner: ^2.4.13  # Only needed for annotation-based routes

Then run:

flutter pub get

🚀 Choose Your Navigation Approach

NavKit supports two powerful ways to define routes in your app. Choose the one that fits your needs:

📝 1. Annotation-Based Routes (Recommended for Most Apps)

Perfect for: Apps that want automatic route generation with minimal boilerplate.

Use @NavkitRoute annotations on your screens and let NavKit generate route constants automatically.

@NavkitRoute(isInitial: true)
class HomeScreen extends StatelessWidget {
  // Your screen code
}

// Navigate using generated constants
context.toNamed(NavkitRoutes.homeScreen);

✅ Pros:

  • Automatic route name generation
  • Type-safe constants
  • Less boilerplate
  • IDE autocomplete support

👉 Read the Annotation-Based Routes Guide

🎨 2. Programmatic Generated Routes (Full Control)

Perfect for: Apps that need fine-grained control over transitions and route configuration.

Define routes programmatically using NavKitGeneratedRoute with custom transitions per route.

final appRoutes = [
  NavKitGeneratedRoute(
    name: '/',
    page: const HomeScreen(),
    transitionType: NavKitGeneratedRouteTransitionType.fade,
    duration: const Duration(milliseconds: 400),
  ),
  NavKitGeneratedRoute(
    name: '/profile',
    page: const ProfileScreen(),
    transitionType: NavKitGeneratedRouteTransitionType.slideRight,
  ),
];

// In NavkitMaterialApp
NavkitMaterialApp(
  generatedRoutes: appRoutes,
  generatedFailureRoute: NavKitGeneratedRoute(
    page: const NotFoundScreen(),
  ),
)

✅ Pros:

  • Full control over transitions per route
  • Custom 404 pages
  • No build runner needed
  • Centralized route definitions

👉 Read the Generated Routes Guide

🎯 Navigation Features

Both approaches give you access to NavKit's powerful navigation extensions:

Quick Navigation Examples:

// Named navigation
context.toNamed('/profile');

// Direct widget navigation
context.to(const ProfileScreen());

// Animated transitions
context.toWithFade(const SettingsScreen());
context.toWithSlide(const ProfileScreen());
context.toWithScale(const DetailsScreen());

// Pop operations
context.back();
context.backMultiple(3);
context.backToFirst();

// UI helpers
context.showSheet(builder: (context) => MyBottomSheet());
context.showAppDialog(builder: (context) => MyDialog());
context.showSnackBar(content: const Text('Success!'));

// Stack management
bool canPop = context.canPop;
bool inStack = context.isRouteInStack('/profile');
String? current = context.currentRouteName;

👉 Read the Complete Navigation Fundamentals Guide

📚 Documentation

Complete Guides:

  1. Annotated Routes Guide

    • Using @NavkitRoute annotations
    • Automatic route generation with build_runner
    • Best practices for annotations

  2. Generated Routes Guide

    • Using NavKitGeneratedRoute programmatically
    • Custom transitions per route
    • Custom 404 pages

  3. Navigation Fundamentals

    • All navigation extensions and methods
    • UI helpers (dialogs, sheets, snackbars)
    • Navigation observer
    • Stack management

⚡ Quick Comparison

Feature Annotation-Based Generated Routes
Route Definition @NavkitRoute() on classes NavKitGeneratedRoute list
Build Runner ✅ Required ❌ Not needed
Type-Safe Constants ✅ Auto-generated ⚠️ Manual constants recommended
Custom Transitions Per navigation call Per route definition
404 Handling Default screen Custom generatedFailureRoute
Learning Curve Easy Medium
Flexibility Medium High

🎨 Available Transition Types

Both approaches support these beautiful transitions:

  • Fade - Smooth opacity transition
  • Scale - Zoom in/out effect
  • SlideRight - Slide from left to right
  • SlideLeft - Slide from right to left
  • SlideUp - Slide from bottom to top
  • SlideDown - Slide from top to bottom
  • Rotation - Rotate with fade effect
  • Size - Grow/shrink animation with fade

🔍 Navigation Observer

Track all navigation events with beautiful console logs:

NavkitMaterialApp(
  observeWithStack: true,  // Enable detailed logging
  // ... your routes
)

Console output:

➡️ Push → ProfileScreen (from: HomeScreen)
────────────────────────────────────
📚 Route Stack:
   • Initial
   • HomeScreen
   • ProfileScreen
────────────────────────────────────

🎯 Best Practices

✅ DO:

  • Choose one approach and stick with it throughout your app
  • Enable observeWithStack: true during development for debugging
  • Use named navigation for better type safety
  • Check route existence before navigating in production
  • Handle navigation results with null checks
  • Use appropriate transitions for each screen's purpose

❌ DON'T:

  • Don't mix both approaches in the same app (choose one)
  • Don't navigate without checking if routes exist
  • Don't pass large objects through route arguments
  • Don't use overly long transitions (>1 second)

🐛 Troubleshooting

Routes Not Working?

  1. Verify you've chosen the correct approach (annotation or programmatic)
  2. Enable observeWithStack: true to see navigation logs
  3. Check the specific guide for your approach:
  1. Check console for error messages
  2. Verify route names match exactly
  3. Ensure routes are properly registered
  4. See Navigation Fundamentals - Troubleshooting

📊 Package Stats

  • 📦 Version: 2.0.2
  • ⭐ GitHub: flutter_navkit
  • 📱 Platforms: iOS, Android, Web, Desktop

📄 License

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

📬 Support & Contact

⭐ Show Your Support

If you find this package helpful:

  • 👍 Like it on pub.dev
  • ⭐ Star the repo on GitHub
  • 📢 Share with the Flutter community
  • 🐛 Report issues to help improve the package

Made by Rado Dayef

Happy Navigating! 🚀

Libraries

annotations
builder
flutter_navkit