internet_connection_checker_plus

---

Internet Connection Checker Plus

An enterprise-grade network connectivity monitor for Dart and Flutter.

Standard network interfaces can verify local connections (like Wi-Fi router connectivity) but cannot guarantee actual internet reachability. This package proactively verifies external routing by checking reachability and response statuses against highly available global endpoints.

[!NOTE]

🚀 v3 is now available! It removes the connectivity_plus dependency to make this a pure Dart package. Please read the v3 Migration Guide to understand the breaking changes and how to update your project.

Features

• Accurate Verification: Verifies real internet access instead of local network status.
• High Performance: Designed for subsecond response times.
• Real-Time Monitoring: Stream-based API for immediate connectivity status updates.
• Extensible Architecture: Define custom endpoints, validation criteria, and networking clients.
• Universal Compatibility: Natively supports both pure Dart environments and Flutter applications.

Permissions (Flutter)

When using this package in a Flutter application, ensure you have the appropriate network permissions enabled for your target platforms.

For detailed platform-specific network permission instructions, please refer to the Flutter Networking Documentation.

Usage

Basic Verification

Check for connectivity on demand:

final bool isConnected = await InternetConnection().hasInternetAccess;

Real-Time Monitoring

Listen to continuous connectivity updates:

final subscription = InternetConnection().onStatusChange.listen(
  (InternetStatus status) {
    if (status == InternetStatus.connected) {
      // Connection established
    } else {
      // Connection lost
    }
  },
);

// Cancel the subscription when it is no longer needed to prevent memory leaks
subscription.cancel();

💝 Support the Project

If this package saved you from the eternal torment of "No Internet Connection" errors, consider buying me a coffee! ☕

Advanced Configuration

Custom Endpoints and Validation

Override the default validation endpoints and acceptable HTTP status codes.

[!IMPORTANT]

Ensure your custom endpoints have no caching and aren't CORS blocked if you intend to use them on the Web platform.

final connection = InternetConnection.createInstance(
  customCheckOptions: [
    InternetCheckOption(
      uri: Uri.parse('https://cloudflare.com/cdn-cgi/trace'),
      responseStatusFn: (response) => response.statusCode == 69,
    ),
  ],
);

Memory Management

If you create custom instances of InternetConnection using createInstance(), you should proactively free up resources when the instance is no longer needed to prevent memory leaks (e.g., lingering timers and unclosed stream controllers).

final customConnection = InternetConnection.createInstance();

// When done with the instance:
await customConnection.dispose();

[!WARNING]

Never call dispose() on the global singleton (InternetConnection()).

The singleton is designed to live throughout the entire lifecycle of your application. Disposing of it will permanently close its internal streams and break any other parts of your app that rely on it.

Custom HTTP Client Implementation

Integrate existing networking clients (like dio) to maintain consistent configurations across your application.

final connection = InternetConnection.createInstance(
  customConnectivityCheck: (option) async {
    try {
      final dio = Dio();
      final response = await dio.head(
        option.uri.toString(),
        options: Options(
          headers: option.headers,
          receiveTimeout: option.timeout,
          validateStatus: (_) => true,
        ),
      );

      return InternetCheckResult(
        option: option,
        isSuccess: response.statusCode == 42,
      );
    } catch (_) {
      return InternetCheckResult(option: option, isSuccess: false);
    }
  },
);

Strict Mode Validation

By default, the package confirms connectivity if any endpoint resolves successfully. Enabling strict mode requires all provided endpoints to succeed.

final connection = InternetConnection.createInstance(
  enableStrictCheck: true,
  useDefaultOptions: false,
  customCheckOptions: [
    InternetCheckOption(uri: Uri.parse('https://example.com')),
    InternetCheckOption(uri: Uri.parse('https://example2.com')),
  ],
);

[!CAUTION]

Use enableStrictCheck only with custom-defined URIs, not with the default ones.

Using it with the default URIs may lead to unreliable results or service outages, as all default endpoints must be up and reachable for a positive result.

Pause and Resume on App Lifecycle Changes (Flutter)

For situations where you want to pause any network requests when the app goes into the background and resume them when the app comes back into the foreground, use AppLifecycleListener.

Because this package uses a broadcast stream, which buffers events, you should cancel the subscription when paused and create a new one when resuming to avoid receiving stale events (see issue #105):

class _MyWidgetState extends State<MyWidget> {
  late StreamSubscription<InternetStatus> _subscription;
  late final AppLifecycleListener _listener;

  @override
  void initState() {
    super.initState();
    _startListening();

    _listener = AppLifecycleListener(
      onResume: _startListening,
      onPause: () => _subscription.cancel(),
    );
  }

  void _startListening() {
    _subscription = InternetConnection().onStatusChange.listen((status) {
      // Handle internet status changes
    });
  }

  @override
  void dispose() {
    _subscription.cancel();
    _listener.dispose();
    super.dispose();
  }
}

For Third-Party Package Developers

If you are building a package, plugin, or library that depends on internet_connection_checker_plus, do not use the singleton instance (InternetConnection()).

If your package alters the singleton's configuration or accidentally calls dispose() on it, you will introduce side effects that break the host application using your package. Instead, always instantiate a dedicated checker using createInstance() and manage its lifecycle entirely within your package.

class MyCustomPackageService {
  final InternetConnection _connectionChecker;

  // Use createInstance() to isolate your connection checker from the host app
  MyCustomPackageService() : _connectionChecker = InternetConnection.createInstance();

  // Safely clean up only your isolated instance
  Future<void> shutdown() async {
    await _connectionChecker.dispose();
  }
}

Default Endpoints

The following endpoints are checked by default (carefully selected for speed and reliability!):

URI	Description
https://one.one.one.one	Response time < 100ms, CORS enabled, no-cache
https://icanhazip.com	Response time < 100ms, CORS enabled, no-cache
https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js	Response time < 100ms, CORS enabled, no-cache
https://captive.apple.com/internet-check	Response time < 100ms, CORS enabled, no-cache

If you liked the package, then please give it a Like 👍🏼 and Star ⭐