Smart Connectivity Checker 🌐 #

A production-ready Flutter package that monitors real internet connectivity with high accuracy—distinguishing between no connection, weak/slow connection, and good connectivity. Automatically displays customizable SnackBars and provides callbacks for programmatic handling.

📋 Table of Contents #

• Features
• Why Smart Connectivity Checker?
• Installation
• Quick Start
• Architecture Overview
• Usage Guide
  • Basic Usage
  • Advanced Configuration
  • Programmatic Monitoring
  • Disabling Auto SnackBar
• API Reference
• Connection Quality States
• Platform Setup
• Configuration Options
• Real-World Examples
• Testing
• Troubleshooting
• Performance & Best Practices
• Known Limitations
• FAQ
• Contributing
• License

✨ Features #

✅ Real Internet Verification — Uses DNS lookup (InternetAddress.lookup) to verify actual internet connectivity, not just Wi-Fi/mobile presence

✅ Three-Tier Connection Quality — Detects none (no internet), weak (slow connection), and good (fast connection)

✅ Automatic SnackBar Display — Shows status changes with color-coded messages (red/orange/green) and customizable duration

✅ Retry Mechanism — "Retry" button on the no-internet SnackBar for immediate re-checks

✅ Callback Support — Optional onConnectionChanged callback for programmatic handling

✅ Dual Monitoring Strategy —

• Listens to OS connectivity changes (network available/unavailable)
• Periodic deep checks every 8 seconds to catch "connected but no internet" scenarios

✅ Zero Linting Warnings — Fully adheres to Flutter best practices and linters

✅ Proper Context Handling — Safe async/await patterns with mounted checks; no use_build_context_synchronously warnings

✅ Lightweight & Dependency-Minimal — Only depends on connectivity_plus

✅ Null-Safe & Modern — Dart 3.3+, pattern matching, const constructors

❓ Why Smart Connectivity Checker? #

Common Problem: Most connectivity packages only check if a network interface exists. They don't verify actual internet access. This leads to:

• Apps showing "connected" when Wi-Fi is present but has no internet
• Users encountering silent network failures in feature-critical flows

The Solution:

┌─ Traditional Approach (connectivity_plus alone)
│  "Is Wi-Fi/mobile available?" → YES → ✅ Connected
│  (But no actual internet!)
│
└─ Smart Connectivity Checker
   "Is Wi-Fi/mobile available?" → YES → "Can I reach DNS?" → NO → ❌ No Internet
   (Real verification via DNS lookup)

Smart Connectivity Checker combines OS-level connectivity monitoring with real DNS verification for the most accurate internet status.

📦 Installation #

Add to pubspec.yaml #

dependencies:
  flutter:
    sdk: flutter
  smart_connectivity_checker: ^0.1.0

Run flutter pub get #

flutter pub get

🚀 Quick Start #

Minimal Setup (3 lines) #

import 'package:flutter/material.dart';
import 'package:smart_connectivity_checker/smart_connectivity_checker.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: InternetChecker(
        child: const MyHomePage(),
      ),
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('My App')),
      body: const Center(child: Text('Connection status auto-monitored!')),
    );
  }
}

That's it! Your app now automatically:

• ✅ Monitors internet connectivity in the background
• ✅ Shows SnackBars when status changes
• ✅ Displays a "Retry" button for no-internet scenarios

🏗️ Architecture Overview #

Smart Connectivity Checker uses a clean separation of concerns:

Three-Layer Architecture #

┌─────────────────────────────────────────┐
│ InternetChecker (Widget Layer)           │
│ • Wraps your app                         │
│ • Manages SnackBar display               │
│ • Safe context usage with mounted check  │
└──────────────┬──────────────────────────┘
               │ (listens via callback)
┌──────────────▼──────────────────────────┐
│ InternetMonitor (Monitor Layer)          │
│ • Pure logic (no BuildContext)           │
│ • Monitors connectivity in background    │
│ • Performs OS + DNS checks               │
│ • Emits ConnectionQuality changes        │
└──────────────┬──────────────────────────┘
               │ (uses DNS + OS APIs)
┌──────────────▼──────────────────────────┐
│ ConnectionQuality (Data Layer)           │
│ • Enum: none | weak | good               │
│ • Built-in display helpers               │
│ • displayMessage, displayColor, etc.     │
└─────────────────────────────────────────┘

Why this design?

• InternetMonitor has no Flutter dependencies, making it testable and reusable
• InternetChecker widget handles all UI/context concerns
• ConnectionQuality enum is a simple, immutable data type

📚 Usage Guide #

Basic Usage #

The simplest way to add connectivity monitoring to your app:

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: InternetChecker(
        child: const MyHomePage(),
      ),
    );
  }
}

What happens automatically:

• When app starts: Initial connectivity check
• On network change: OS notifies, package re-checks
• Every 8 seconds: Periodic verification
• On any change: SnackBar is displayed (customizable message/color)

Advanced Configuration #

Fine-tune monitoring behavior for your specific needs:

InternetChecker(
  child: const MyApp(),
  
  // Control SnackBar display
  showSnackBar: true,                              // default: true
  snackBarDuration: const Duration(seconds: 5),   // default: 4 seconds
  
  // Customize connectivity verification
  pingHost: 'google.com',                          // default: google.com
  pingTimeout: const Duration(seconds: 8),         // default: 6 seconds
  
  // Adjust sensitivity
  weakThreshold: const Duration(seconds: 2),       // default: 3 seconds
  checkInterval: const Duration(seconds: 10),      // default: 8 seconds
  
  // Listen to changes programmatically
  onConnectionChanged: (quality) {
    print('Connection quality: $quality');
    // Log to analytics, update UI state, etc.
  },
)

Programmatic Monitoring #

Access the ConnectivityQuality directly via the callback:

InternetChecker(
  child: const MyApp(),
  onConnectionChanged: (quality) {
    switch (quality) {
      case ConnectionQuality.none:
        // No internet - show offline UI
        _analytics.logEvent('offline');
        break;
      case ConnectionQuality.weak:
        // Weak connection - warn user
        _showWarning('Your connection is slow...');
        break;
      case ConnectionQuality.good:
        // Good connection - proceed normally
        _syncData();
        break;
    }
  },
)

Accessing Connection State Within Your App

Use InternetMonitor directly if you need to check state without SnackBars:

import 'package:smart_connectivity_checker/smart_connectivity_checker.dart';

class MyWidget extends StatefulWidget {
  const MyWidget({super.key});

  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  late InternetMonitor _monitor;

  @override
  void initState() {
    super.initState();
    _monitor = InternetMonitor(
      onConnectionChanged: (quality) {
        setState(() {
          // Update UI when connection changes
        });
      },
    );
    _monitor.startMonitoring();
  }

  @override
  void dispose() {
    _monitor.stopMonitoring();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final current = _monitor.currentQuality;
    return Text('Status: ${current.displayMessage}');
  }
}

Disabling Auto SnackBar #

If you want to handle all UI updates yourself:

InternetChecker(
  child: const MyApp(),
  showSnackBar: false,  // ← Disable automatic SnackBars
  onConnectionChanged: (quality) {
    // Handle all UI updates here
    _showCustomUI(quality);
  },
)

📖 API Reference #

InternetChecker (Widget) #

The main widget wrapper for your app.

Constructor Parameters

Example

InternetChecker(
  child: MyApp(),
  showSnackBar: true,
  snackBarDuration: const Duration(seconds: 5),
  pingHost: 'cloudflare.com',
  pingTimeout: const Duration(seconds: 10),
  weakThreshold: const Duration(seconds: 4),
  checkInterval: const Duration(seconds: 15),
  onConnectionChanged: (quality) {
    print('Connection changed to: $quality');
  },
)

InternetMonitor (Class) #

The core monitoring logic. Use directly if you need fine-grained control.

Constructor

InternetMonitor({
  ConnectionCallback? onConnectionChanged,
  String pingHost = 'google.com',
  Duration pingTimeout = const Duration(seconds: 6),
  Duration weakThreshold = const Duration(seconds: 3),
  Duration checkInterval = const Duration(seconds: 8),
})

Key Methods

startMonitoring() → Future<void>

Starts background monitoring. Safe to call multiple times.

await _monitor.startMonitoring();

stopMonitoring() → void

Stops all monitoring and cleans up resources.

_monitor.stopMonitoring();

retry() → Future<ConnectionQuality>

Immediately re-checks connectivity. Useful for "Retry" button handlers.

final newQuality = await _monitor.retry();

Properties

currentQuality → ConnectionQuality

Get the current detected connection quality.

if (_monitor.currentQuality.isConnected) {
  syncData();
}

ConnectionQuality (Enum) #

Represents the current connection state.

Values

enum ConnectionQuality {
  none,   // No network or DNS lookup failed
  weak,   // Network exists but slow/unreliable
  good,   // Fast, stable internet
}

Properties & Methods

Usage Examples

final quality = ConnectionQuality.good;

// Check connection status
if (quality.isConnected) {
  // Safe to proceed with network requests
}

// Conditional logic
if (quality == ConnectionQuality.none) {
  showOfflineUI();
} else if (quality == ConnectionQuality.weak) {
  showWarning('Slow connection detected');
}

// Display helpers
print(quality.displayMessage);  // "Internet connection restored"
widget.backgroundColor = quality.displayColor;  // Green

🔍 Connection Quality States #

The package detects three distinct connection states:

1️⃣ NONE (No Internet) #

• Condition: No network interface available OR DNS lookup fails
• SnackBar: Red background, "No internet connection"
• Action Button: "Retry" (triggers immediate re-check)
• Display Color: Color(0xFFD32F2F) (Material Red)

// Examples of triggering NONE:
// - Wi-Fi is off, mobile data is off
// - Wi-Fi connected but no internet (e.g., captive portal)
// - DNS server unreachable
// - DNS lookup times out

2️⃣ WEAK (Slow Connection) #

• Condition: Network exists, DNS lookup succeeds, but takes > weakThreshold (default: 3 seconds)
• SnackBar: Orange background, "Weak internet connection"
• Action Button: None (no retry button)
• Display Color: Color(0xFFF57C00) (Material Orange)

// Examples of triggering WEAK:
// - LTE on poor signal with DNS taking 4+ seconds
// - Satellite connection
// - 3G with congestion
// - Proxy with slow response

3️⃣ GOOD (Normal Internet) #

• Condition: Network exists, DNS lookup succeeds, and responds < weakThreshold
• SnackBar: Green background, "Internet connection restored"
• Action Button: None
• Display Color: Color(0xFF388E3C) (Material Green)

// Examples of triggering GOOD:
// - Wi-Fi with normal broadband
// - LTE on good signal
// - 5G
// - Fast tethering

State Transition Flow #

App Start
   ↓
Initial Check (sync on first frame)
   ↓
QUALITY_X (none/weak/good)
   ├─ Listen to OS connectivity changes
   │  └─ Network available? → Re-check → Possibly transition
   │
   └─ Periodic timer (every 8 seconds)
      └─ Re-check quality → Possibly transition

On Each Transition (Quality Change):
   1. Update internal state
   2. Call onConnectionChanged callback (if set)
   3. Show SnackBar (if showSnackBar=true)

🛠️ Platform Setup #

Android #

Permissions Required

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Example:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
  
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  
  <application ...>
    <!-- Your app configuration -->
  </application>
  
</manifest>

Automatic Setup

If you're missing these, the package will still work on Android 6.0+, but may not detect connection state changes immediately.

iOS #

No Additional Setup Required

Smart Connectivity Checker uses standard iOS APIs that don't require special permissions. The app will monitor:

• Wi-Fi status via CNCopyCurrentNetworkInfo()
• Cellular status via NWPathMonitor
• DNS resolution via InternetAddress.lookup()

Info.plist (Optional)

To enable background connectivity checks, optionally add:

<key>NSBonjourServices</key>
<array>
  <string>_http._tcp</string>
</array>

(Most apps can skip this unless you need background monitoring.)

macOS, Windows, Linux #

Fully supported. No additional configuration needed beyond flutter pub get.

⚙️ Configuration Options #

Quick Reference Table #

Common Configurations #

🏢 Corporate Environment

InternetChecker(
  child: MyApp(),
  pingHost: 'cloudflare.com',  // Try alternative DNS
  pingTimeout: const Duration(seconds: 10),  // Proxy may be slow
)

📱 Battery-Conscious App

InternetChecker(
  child: MyApp(),
  checkInterval: const Duration(seconds: 30),  // Check less often
  weakThreshold: const Duration(seconds: 5),   // Be more lenient
)

🎮 Multiplayer Game (Strict)

InternetChecker(
  child: MyApp(),
  pingHost: 'google.com',
  pingTimeout: const Duration(seconds: 3),     // Fail fast
  weakThreshold: const Duration(seconds: 1),   // Strict QoE
  checkInterval: const Duration(seconds: 5),   // Check often
)

📊 Analytics/Logging

InternetChecker(
  child: MyApp(),
  showSnackBar: false,  // Silent monitoring
  onConnectionChanged: (quality) {
    _analytics.logEvent(
      'connectivity_changed',
      parameters: {'quality': quality.toString()},
    );
  },
)

💡 Real-World Examples #

Example 1: E-Commerce App #

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: InternetChecker(
        child: const HomePage(),
        onConnectionChanged: (quality) {
          // Track for analytics
          if (quality == ConnectionQuality.none) {
            print('User is offline - purchase button disabled');
          }
        },
      ),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Shop')),
      body: ListView(
        children: [
          // Products...
        ],
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          // Checkout button can monitor quality
        },
        child: const Icon(Icons.shopping_cart),
      ),
    );
  }
}

Example 2: Social Media App #

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  ConnectionQuality _quality = ConnectionQuality.good;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: InternetChecker(
        child: const HomePage(),
        onConnectionChanged: (quality) {
          setState(() => _quality = quality);
          
          // Upload queue management
          if (quality.isConnected && _quality != ConnectionQuality.good) {
            // Just regained connection, sync pending posts
            _syncPendingPosts();
          }
        },
      ),
    );
  }

  void _syncPendingPosts() {
    print('Syncing pending posts...');
  }
}

✅ Testing #

Unit Testing InternetMonitor #

import 'package:flutter_test/flutter_test.dart';
import 'package:smart_connectivity_checker/smart_connectivity_checker.dart';

void main() {
  group('InternetMonitor', () {
    late InternetMonitor monitor;

    setUp(() {
      monitor = InternetMonitor();
    });

    tearDown(() {
      monitor.stopMonitoring();
    });

    test('Initial quality should be none', () {
      expect(monitor.currentQuality, ConnectionQuality.none);
    });

    test('Should call onConnectionChanged callback', () async {
      final qualities = <ConnectionQuality>[];

      monitor = InternetMonitor(
        onConnectionChanged: (quality) {
          qualities.add(quality);
        },
      );

      await monitor.startMonitoring();
      await Future.delayed(const Duration(milliseconds: 500));

      expect(qualities.isNotEmpty, true);
    });

    test('Should stop monitoring and clean up', () async {
      await monitor.startMonitoring();
      monitor.stopMonitoring();

      // Verify no exceptions on multiple stops
      expect(() => monitor.stopMonitoring(), returnsNormally);
    });

    test('Retry should trigger a check', () async {
      final qualities = <ConnectionQuality>[];

      monitor = InternetMonitor(
        onConnectionChanged: (quality) {
          qualities.add(quality);
        },
      );

      await monitor.startMonitoring();
      final beforeRetry = qualities.length;

      await monitor.retry();

      // Should have called callback (or not if already at same quality)
      expect(qualities.length >= beforeRetry, true);
    });
  });
}

🔧 Troubleshooting #

Issue 1: Always Shows "No Network" #

Possible Causes:

1. Permissions not granted (Android)
2. Default pingHost blocked by firewall
3. Device actually has no internet

Solutions:

// Try alternative DNS
InternetChecker(
  child: MyApp(),
  pingHost: 'cloudflare.com',  // Instead of google.com
  pingTimeout: const Duration(seconds: 10),  // Give more time
)

Issue 2: SnackBar Not Showing #

Possible Causes:

1. No Scaffold in widget tree
2. showSnackBar: false
3. SnackBar dismissed by another one
4. Not wrapped in MaterialApp

Solutions:

Ensure MaterialApp → ScaffoldMessenger → Scaffold:

MaterialApp(
  home: InternetChecker(  // ✅ Below MaterialApp
    child: Scaffold(      // ✅ Has Scaffold
      body: MyContent(),
    ),
  ),
)

Issue 3: High Battery Drain #

Possible Causes:

1. checkInterval too short (default 8s is fine)
2. App is checking during background

Solutions:

InternetChecker(
  child: MyApp(),
  checkInterval: const Duration(seconds: 30),  // Increase interval
)

Issue 4: Monitoring Stops in Background #

Expected Behavior: Android/iOS stop networking APIs when app backgrounded.

If you need background monitoring:

• Use plugins like workmanager or background_fetch
• Implement periodic background tasks separately

🚀 Performance & Best Practices #

Memory Impact #

• Average: ~2-3 MB (StreamSubscription + Timer)
• Negligible compared to typical Flutter app

Battery Impact #

• Default (8-second checks): ~0.5-1% per hour
• Configurable: Adjust checkInterval to balance accuracy vs. battery

CPU Usage #

• Each check: ~10-50ms (DNS lookup is the costly part)
• Default frequency: 8 seconds → ~1-2% CPU average

Best Practices #

1. Use Default Settings in Most Cases

   InternetChecker(child: MyApp())  // ✅ Good for 99% of apps
   

2. Disable SnackBar for Silent Monitoring

   InternetChecker(
     child: MyApp(),
     showSnackBar: false,
     onConnectionChanged: (quality) => _handleChange(quality),
   )
   

3. Increase checkInterval for Battery-Sensitive Apps

   InternetChecker(
     child: MyApp(),
     checkInterval: const Duration(seconds: 15),
   )
   

⚠️ Known Limitations #

1. Ping Host Must Be Reachable

   • Default: google.com
   • Some corporate networks block Google DNS
   • Solution: Use pingHost: 'cloudflare.com'

2. No Bandwidth Measurement

   • Package detects connectivity, not speed in Mbps
   • Use weakThreshold parameter to define "slow"

3. Background Monitoring Limited

   • iOS/Android pause networking when app backgrounded

4. Custom Colors Not Supported

   • SnackBar colors are fixed (red/orange/green)
   • Workaround: Use showSnackBar: false and handle UI yourself

❓ FAQ #

Q: How does Smart Connectivity Checker differ from connectivity_plus? #

A: connectivity_plus checks if a network interface exists. Smart Connectivity Checker goes further with DNS verification.

Q: Can I customize the SnackBar colors? #

A: Currently fixed. Workaround: Disable auto SnackBar and build your own.

Q: Is it safe to use in production? #

A: Yes! Passes all linter checks, proper async patterns, no memory leaks.

Q: What if the user is offline when the app starts? #

A: Package handles gracefully—shows red SnackBar with Retry button.

Q: Can I use it with Google Maps, Firebase, etc.? #

A: Absolutely! Works alongside any service.

Q: Can I use it with state management (Riverpod, GetX, Bloc)? #

A: Yes! Framework-agnostic design.

Q: What's the minimum Flutter version? #

A: Flutter 3.19.0+

🤝 Contributing #

We welcome contributions! Report issues, suggest features, or submit PRs on GitHub.

📄 License #

Smart Connectivity Checker is released under the MIT License.

📞 Support #

• 📖 Documentation: See this README
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Happy coding! 🚀