🧭 Flutter NavKit #

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

✨ 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 #

🎨 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:
   • Annotation-Based Troubleshooting
   • Generated Routes Troubleshooting

Navigation Fails Silently? #

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 #

• 📦 Package: pub.dev
• 🐛 Issues: Report a bug

⭐ 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! 🚀