How to Handle Network Connectivity Changes in Flutter: Complete Guide

Network connectivity is an essential part of modern Flutter applications. Whether your app uses REST APIs, Firebase, Supabase, or other online services, a stable internet connection is often required to provide a smooth user experience.

However, users do not always have reliable internet access. They may switch between Wi-Fi and mobile data, enter areas with poor network coverage, enable airplane mode, or temporarily lose connectivity while using your application.

If your Flutter app does not handle these situations properly, users may experience failed API requests, endless loading indicators, lost form data, or unexpected errors.

Flutter provides several ways to detect network connectivity changes and respond to them appropriately.

In this guide, you will learn how to handle network connectivity changes in Flutter using the connectivity_plus package, detect internet availability, monitor network changes in real time, implement connectivity handling with GetX, retry failed API requests, and build a better offline user experience.

1. Understanding Network Connectivity in Flutter

Before implementing connectivity handling, it is important to understand the difference between network connectivity and actual internet availability.

These are not the same thing.

Network connectivity indicates whether a device is connected to a network interface, such as Wi-Fi, mobile data, or Ethernet.

Internet availability indicates whether the device can actually communicate with services on the internet.

For example, a device may be connected to Wi-Fi but still have no internet access because of a router problem, captive portal, or internet service provider outage.

Similarly, a device may have internet access while your application’s backend server is unavailable.

A reliable Flutter application should distinguish between these conditions.

Network condition	Recommended application behavior
Wi-Fi connected with internet	Continue normal application operations.
Wi-Fi connected without internet	Show an appropriate connection error when requests fail.
Mobile data connected	Continue operations while respecting data usage.
No network connection	Display an offline state and avoid unnecessary requests.
Network connection restored	Refresh relevant data or retry eligible failed operations.
Backend server unavailable	Display a service error rather than incorrectly reporting that the device is offline.

The key principle is that detecting a network interface alone does not guarantee that your API requests will succeed.

2. Install the connectivity_plus Package

The connectivity_plus package allows Flutter applications to detect available network connection types and listen for connectivity changes.

It supports Android, iOS, macOS, Windows, Linux, and web, subject to platform-specific limitations.

Official package: https://pub.dev/packages/connectivity_plus

Install the package using the Flutter CLI:

flutter pub add connectivity_plus

Alternatively, add the package to your pubspec.yaml file using a version compatible with your Flutter SDK.

dependencies:
  flutter:
    sdk: flutter

  connectivity_plus: ^7.0.0

Then run:

flutter pub get

The examples in this guide use the modern connectivity_plus API, which returns a list of connectivity results rather than a single connectivity result.

Check the package’s official documentation for the SDK requirements and API changes applicable to the version installed in your project.

3. Check the Current Network Connectivity

The first step is checking whether the device currently has an available network connection.

The Connectivity class provides the checkConnectivity() method for this purpose.

Example: Check network connectivity

import 'package:connectivity_plus/connectivity_plus.dart';

Future<void> checkNetworkConnection() async {
  final connectivity = Connectivity();

  final List<ConnectivityResult> results =
      await connectivity.checkConnectivity();

  if (results.contains(ConnectivityResult.none)) {
    print('No network connection');
  } else {
    print('Network connection available');
  }
}

The method returns the available network connection types.

For example, the device may report Wi-Fi, mobile data, or another supported network interface.

Important: This method checks network connectivity, not whether the device can successfully access your backend or the public internet.

For a production application, verify connectivity before important operations when useful, but always handle the actual request result as well.

4. Detect Wi-Fi and Mobile Data Connections

Sometimes, your application needs to know which type of network the user is using.

For example, a video streaming application may reduce video quality on mobile data, while a file synchronization application may allow users to download large files only when Wi-Fi is available.

You can identify the reported connection types using ConnectivityResult.

import 'package:connectivity_plus/connectivity_plus.dart';

Future<void> checkConnectionType() async {
  final results =
      await Connectivity().checkConnectivity();

  if (results.contains(ConnectivityResult.wifi)) {
    print('Wi-Fi connection available');
  }

  if (results.contains(ConnectivityResult.mobile)) {
    print('Mobile data connection available');
  }

  if (results.contains(ConnectivityResult.ethernet)) {
    print('Ethernet connection available');
  }

  if (results.contains(ConnectivityResult.none)) {
    print('No network connection');
  }
}

Other connection types may include Bluetooth, VPN, and platform-specific connections.

Because the API returns a list, multiple connection types may be reported.

Do not assume that the device is connected to only one network interface.

Also, Wi-Fi connectivity does not necessarily mean the network is unmetered or that large downloads are appropriate.

5. Listen for Network Connectivity Changes in Real Time

Checking connectivity once is not enough for applications that remain open for long periods.

A user may open your application while connected to Wi-Fi and then lose connectivity while navigating between screens.

The onConnectivityChanged stream allows you to listen for changes in available network interfaces.

Example: Monitor connectivity changes

import 'dart:async';

import 'package:connectivity_plus/connectivity_plus.dart';

class ConnectivityService {
  final Connectivity _connectivity = Connectivity();

  StreamSubscription<List<ConnectivityResult>>?
      _subscription;

  void startMonitoring() {
    _subscription = _connectivity.onConnectivityChanged.listen(
      (List<ConnectivityResult> results) {
        if (results.contains(ConnectivityResult.none)) {
          print('Device is offline');
        } else {
          print('Network connection available');
        }
      },
    );
  }

  Future<void> stopMonitoring() async {
    await _subscription?.cancel();
    _subscription = null;
  }
}

Start monitoring when your application needs connectivity updates.

Cancel the subscription when the service is no longer required.

Otherwise, unused listeners may remain active and cause unnecessary processing or resource retention.

Why connectivity events should not be treated as guaranteed internet status

A connectivity event only reports a change in the available network interfaces.

It does not confirm that a remote server is reachable.

Some platforms may also emit multiple or rapidly changing connectivity events during a network transition.

For example, switching from Wi-Fi to mobile data may temporarily produce a disconnected state before the new connection becomes available.

Your application should avoid repeatedly displaying offline messages or triggering duplicate API requests during these transitions.

6. Build a Reusable Connectivity Service in Flutter

Instead of checking network connectivity separately on every screen, create a reusable service.

This makes your application easier to maintain and keeps connectivity logic separate from the UI.

Create the following file:

lib/core/services/connectivity_service.dart

import 'dart:async';

import 'package:connectivity_plus/connectivity_plus.dart';

class ConnectivityService {
  final Connectivity _connectivity = Connectivity();

  final StreamController<bool> _connectionController =
      StreamController<bool>.broadcast();

  StreamSubscription<List<ConnectivityResult>>?
      _subscription;

  bool _hasNetwork = false;

  bool get hasNetwork => _hasNetwork;

  Stream<bool> get connectionStream =>
      _connectionController.stream;

  Future<void> initialize() async {
    final results =
        await _connectivity.checkConnectivity();

    _updateConnection(results);

    _subscription ??=
        _connectivity.onConnectivityChanged.listen(
      _updateConnection,
    );
  }

  void _updateConnection(
    List<ConnectivityResult> results,
  ) {
    final isConnected =
        !results.contains(ConnectivityResult.none) &&
        results.isNotEmpty;

    if (_hasNetwork == isConnected) {
      return;
    }

    _hasNetwork = isConnected;

    if (!_connectionController.isClosed) {
      _connectionController.add(isConnected);
    }
  }

  Future<void> dispose() async {
    await _subscription?.cancel();
    _subscription = null;

    await _connectionController.close();
  }
}

This service provides a centralized way to access the latest reported network state and listen for connectivity changes.

It also prevents repeated identical Boolean connectivity events from being emitted.

However, the hasNetwork property represents network availability, not verified internet access.

For an application-wide service, initialize it once and keep it alive for the required application lifecycle.

7. Handle Connectivity Changes Using GetX

If your Flutter application uses GetX for state management, you can create a dedicated connectivity controller.

GetX allows you to expose connectivity state as a reactive variable and update the UI automatically when the state changes.

Step 1: Create a connectivity controller

Create:

lib/core/controllers/connectivity_controller.dart

import 'dart:async';

import 'package:connectivity_plus/connectivity_plus.dart';
import 'package:get/get.dart';

class ConnectivityController extends GetxController {
  final Connectivity _connectivity = Connectivity();

  final RxBool isConnected = true.obs;

  StreamSubscription<List<ConnectivityResult>>?
      _subscription;

  @override
  void onInit() {
    super.onInit();

    checkConnectivity();

    _subscription =
        _connectivity.onConnectivityChanged.listen(
      _updateConnection,
    );
  }

  Future<void> checkConnectivity() async {
    final results =
        await _connectivity.checkConnectivity();

    _updateConnection(results);
  }

  void _updateConnection(
    List<ConnectivityResult> results,
  ) {
    isConnected.value =
        results.isNotEmpty &&
        !results.contains(ConnectivityResult.none);
  }

  @override
  void onClose() {
    _subscription?.cancel();

    super.onClose();
  }
}

The controller checks the initial network state and listens for subsequent changes.

Whenever connectivity changes, the reactive isConnected variable updates automatically.

Step 2: Register the controller

Register the controller during application initialization.

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  Get.put(
    ConnectivityController(),
    permanent: true,
  );

  runApp(const MyApp());
}

Using permanent: true keeps the controller available throughout the application lifecycle.

This is useful when connectivity monitoring is required across multiple screens.

Step 3: Display connectivity status in the UI

Use Obx to rebuild the relevant widget when the connection state changes.

class HomeScreen extends StatelessWidget {
  HomeScreen({super.key});

  final ConnectivityController controller =
      Get.find<ConnectivityController>();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Home'),
      ),
      body: Obx(() {
        if (!controller.isConnected.value) {
          return const Center(
            child: Text(
              'No network connection available',
            ),
          );
        }

        return const Center(
          child: Text(
            'Network connection available',
          ),
        );
      }),
    );
  }
}

This approach automatically updates the screen when the device’s reported network state changes.

For production applications, avoid replacing an entire screen unnecessarily. Consider displaying a small offline banner while preserving previously loaded content.

8. Show an Offline Banner Without Replacing the Entire Screen

Displaying a full-screen error every time connectivity changes can interrupt the user’s workflow.

For example, a user may be filling out a form when the internet connection temporarily disappears.

Replacing the entire screen could remove the form from view and potentially disrupt the user’s progress.

A better approach is to display a small connectivity banner.

Example: Reusable offline banner

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

  @override
  Widget build(BuildContext context) {
    final controller =
        Get.find<ConnectivityController>();

    return Obx(() {
      if (controller.isConnected.value) {
        return const SizedBox.shrink();
      }

      return Container(
        width: double.infinity,
        padding: const EdgeInsets.symmetric(
          horizontal: 16,
          vertical: 10,
        ),
        color: Colors.red.shade700,
        child: const SafeArea(
          top: false,
          bottom: false,
          child: Row(
            children: [
              Icon(
                Icons.wifi_off,
                color: Colors.white,
                size: 18,
              ),
              SizedBox(width: 10),
              Expanded(
                child: Text(
                  'No network connection',
                  style: TextStyle(
                    color: Colors.white,
                    fontSize: 13,
                  ),
                ),
              ),
            ],
          ),
        ),
      );
    });
  }
}

You can place this widget above the main content of your screen.

Scaffold(
  body: Column(
    children: [
      const OfflineBanner(),

      Expanded(
        child: HomeContent(),
      ),
    ],
  ),
)

This allows users to continue viewing available content while clearly communicating that network-dependent features may not work.

The banner represents the device’s reported network state. A separate request-error message should handle cases where the network is connected but the backend is unreachable.

9. Check Actual Internet Availability in Flutter

The connectivity_plus package detects available network interfaces, but it does not verify that the device can communicate with the internet.

To determine whether a specific service is reachable, you can make a lightweight HTTP request.

For most applications, checking the availability of your own backend is more useful than checking an unrelated public website.

For example, a successful response from a public website does not guarantee that your application’s API server is working.

Example: Check backend availability using Dio

First, install Dio:

flutter pub add dio

Create a service:

import 'package:dio/dio.dart';

class InternetService {
  final Dio _dio = Dio(
    BaseOptions(
      baseUrl: 'https://api.example.com',
      connectTimeout: const Duration(seconds: 5),
      receiveTimeout: const Duration(seconds: 5),
    ),
  );

  Future<bool> isBackendAvailable() async {
    try {
      final response = await _dio.get(
        '/health',
      );

      return response.statusCode == 200;
    } on DioException {
      return false;
    }
  }
}

Replace https://api.example.com with your backend URL.

The /health endpoint is an example. Your backend must provide an appropriate lightweight endpoint for this check.

Ideally, the endpoint should return a successful response when the service is ready to handle requests.

Why checking your backend is useful

Suppose a user is connected to Wi-Fi, but your backend server is temporarily unavailable.

The connectivity package may report that Wi-Fi is available.

However, the backend health check will fail.

This allows your application to distinguish between an unavailable network interface and an unsuccessful backend request.

Important: A failed health check does not always mean the device has no internet. It may indicate a backend outage, DNS problem, timeout, authentication configuration issue, or another network-related failure.

Do not perform health checks continuously or before every API request. Use them when they provide useful information, and rely on actual API responses for operation-specific error handling.

10. Handle Network Failures Properly Using Dio

Even when a connectivity check reports an available network, an API request can fail.

Network connectivity may change between the moment you check it and the moment you send the request.

Therefore, every network-dependent operation should handle its own failures.

Example: Handle common Dio network errors

import 'package:dio/dio.dart';

class ApiService {
  final Dio dio;

  ApiService(this.dio);

  Future<dynamic> fetchUsers() async {
    try {
      final response = await dio.get('/users');

      return response.data;
    } on DioException catch (error) {
      switch (error.type) {
        case DioExceptionType.connectionTimeout:
          throw Exception(
            'Connection timed out. Please try again.',
          );

        case DioExceptionType.sendTimeout:
          throw Exception(
            'Request could not be sent.',
          );

        case DioExceptionType.receiveTimeout:
          throw Exception(
            'Server response timed out.',
          );

        case DioExceptionType.connectionError:
          throw Exception(
            'Unable to connect to the server.',
          );

        case DioExceptionType.badResponse:
          throw Exception(
            'Server returned an error.',
          );

        case DioExceptionType.cancel:
          throw Exception(
            'Request was cancelled.',
          );

        default:
          throw Exception(
            'Something went wrong. Please try again.',
          );
      }
    }
  }
}

This approach ensures that common network failures are handled explicitly instead of producing uncontrolled exceptions.

In larger applications, create typed API exceptions so the UI can distinguish between connection errors, authentication failures, server errors, and other conditions.

Avoid converting every error into a generic “No internet connection” message.

11. Automatically Retry API Requests When Connectivity Returns

A common requirement is refreshing application data after a user regains network connectivity.

For example, suppose the user opens a product listing screen while offline.

The application displays cached data or an error state.

When connectivity returns, the application can attempt to fetch the latest products.

However, not every failed request should be retried automatically.

Read-only requests are generally safer to retry than operations that modify server data.

Example: Refresh data using GetX

import 'package:get/get.dart';

class ProductController extends GetxController {
  final ConnectivityController connectivity =
      Get.find<ConnectivityController>();

  final RxBool isLoading = false.obs;

  final RxList<dynamic> products =
      <dynamic>[].obs;

  Worker? _connectionWorker;

  @override
  void onInit() {
    super.onInit();

    _connectionWorker = ever<bool>(
      connectivity.isConnected,
      (connected) {
        if (connected) {
          fetchProducts();
        }
      },
    );

    if (connectivity.isConnected.value) {
      fetchProducts();
    }
  }

  Future<void> fetchProducts() async {
    if (isLoading.value) return;

    isLoading.value = true;

    try {
      // Fetch products from your repository.
      // Update products only after a successful response.
    } catch (error) {
      print('Failed to fetch products: $error');
    } finally {
      isLoading.value = false;
    }
  }

  @override
  void onClose() {
    _connectionWorker?.dispose();

    super.onClose();
  }
}

This example demonstrates how to react when the reported network state changes from unavailable to available.

The controller must still handle API failures because network availability does not guarantee that the request will succeed.

For production applications, consider debouncing rapid connectivity changes and preventing duplicate refresh requests.

Avoid automatically retrying every failed request

Consider a payment request that reaches the server successfully, but the device loses connectivity before receiving the response.

If the application automatically repeats the request, it could create a duplicate transaction unless the backend implements appropriate safeguards.

For operations such as payments, order creation, and form submission, use backend-supported idempotency keys or verify the original operation’s status before retrying.

12. Implement an Offline-First Approach

For applications that users need to access under unreliable network conditions, detecting connectivity changes is only one part of the solution.

An offline-first architecture allows the application to continue providing useful functionality when the internet is unavailable.

Instead of depending entirely on live API responses, the application stores relevant data locally.

When connectivity returns, the application can synchronize local changes with the backend.

Example: Offline-first data flow

User opens application
        |
        v
Read locally stored data
        |
        v
Display available content
        |
        v
Attempt to fetch fresh data
        |
        v
Update local storage
        |
        v
Refresh the user interface

For write operations, the application may need a separate synchronization queue.

For example, a note-taking application could save a note locally and upload it when connectivity becomes available.

However, offline synchronization requires careful handling of duplicate operations, conflicts, authentication, and partial failures.

Local storage options

Flutter provides several options for storing data locally.

Storage solution	Common use case
shared_preferences	Small application settings and preferences.
SQLite	Structured local data and offline records.
Drift	Reactive database access and structured offline data.
Hive CE	Lightweight local object and key-value storage.

Useful resources:

• shared_preferences: https://pub.dev/packages/shared_preferences
• sqflite: https://pub.dev/packages/sqflite
• Drift: https://pub.dev/packages/drift
• Hive CE: https://pub.dev/packages/hive_ce

Choose the storage solution based on your application’s data structure, synchronization requirements, and supported platforms.

Do not store sensitive authentication credentials in ordinary local preferences or an unencrypted database.

13. Handle Connectivity Changes When the App Returns to the Foreground

Mobile operating systems may restrict background execution.

As a result, your application should not assume that every connectivity change will be delivered while the app is in the background.

For example, a user may:

1. Open the Flutter application.
2. Move the application to the background.
3. Disable Wi-Fi.
4. Enable mobile data.
5. Return to the application.

The application should check the current network state when it resumes.

Flutter provides the WidgetsBindingObserver interface for monitoring application lifecycle changes.

Example: Recheck connectivity when the app resumes

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

class AppLifecycleService with WidgetsBindingObserver {
  final Connectivity _connectivity = Connectivity();

  void initialize() {
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void didChangeAppLifecycleState(
    AppLifecycleState state,
  ) {
    if (state == AppLifecycleState.resumed) {
      checkConnectivity();
    }
  }

  Future<void> checkConnectivity() async {
    final results =
        await _connectivity.checkConnectivity();

    final hasNetwork =
        results.isNotEmpty &&
        !results.contains(ConnectivityResult.none);

    debugPrint(
      'Network available: $hasNetwork',
    );
  }

  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
  }
}

Initialize the service when your application starts and dispose of it when it is no longer needed.

If you already use a centralized connectivity controller, call its existing connectivity-check method instead of creating multiple independent listeners.

This helps keep your application’s connectivity state consistent.

14. Avoid Common Connectivity Handling Mistakes

Several implementation mistakes can make network handling unreliable.

Mistake 1: Assuming Wi-Fi means internet access

A Wi-Fi connection does not guarantee that the device can reach your backend.

Always handle the actual API response.

Mistake 2: Checking connectivity only during startup

Network conditions can change at any time.

Listen for relevant changes and recheck connectivity when the application resumes.

Mistake 3: Creating a connectivity listener on every screen

Unnecessary listeners increase complexity and can cause duplicate events or repeated API requests.

Prefer a centralized service or application-level controller when multiple screens need connectivity information.

Mistake 4: Retrying all requests automatically

Automatically repeating write operations can create duplicate orders, payments, or other server-side changes.

Retry only operations that are safe to repeat, or implement appropriate backend safeguards.

Mistake 5: Removing existing content immediately when offline

Users may still benefit from previously loaded information.

Preserve available content and show a non-intrusive connectivity message whenever possible.

Mistake 6: Making continuous internet-check requests

Frequent health checks can consume battery, mobile data, and backend resources.

Use connectivity events, application lifecycle changes, and actual request failures to decide when additional checks are necessary.

Mistake 7: Treating every API error as a network error

A server may return an authentication error, validation error, or internal server error even when the internet connection is working.

Display messages that accurately represent the failure.

15. Best Practices for Production Flutter Applications

A reliable network-handling implementation should combine connectivity monitoring with request-level error handling and appropriate offline behavior.

Follow these practices:

• Use connectivity_plus to monitor available network interfaces.
• Handle API failures independently of connectivity status.
• Keep connectivity monitoring centralized when multiple screens need it.
• Recheck connectivity when the application returns to the foreground.
• Avoid unnecessary duplicate listeners and API requests.
• Display a small offline banner instead of replacing useful screen content.
• Preserve form input and previously loaded data during temporary connection loss.
• Use request timeouts and appropriate retry policies.
• Avoid automatically retrying non-idempotent operations.
• Cache useful data when offline access is important.
• Synchronize offline changes carefully when connectivity returns.
• Test Wi-Fi-to-mobile-data transitions and temporary network failures.

These practices help your application remain usable and predictable even when network conditions change unexpectedly.

Frequently Asked Questions

How do I detect internet connectivity changes in Flutter?

Use the connectivity_plus package and listen to its onConnectivityChanged stream.

The stream reports changes in available network interfaces, such as Wi-Fi and mobile data.

To verify that your backend is reachable, handle actual API requests or perform an appropriate lightweight health check.

Does connectivity_plus check actual internet access?

No. It reports available network connection types.

A device may be connected to Wi-Fi without having internet access.

Your application should not treat a Wi-Fi or mobile data connection as proof that an API request will succeed.

How can I show a no-internet message in Flutter?

Create a connectivity service or controller that exposes the reported network state.

Use a reactive widget, such as Obx with GetX or StreamBuilder, to display an offline banner when no network interface is available.

Handle backend request failures separately.

How do I automatically refresh data when internet connectivity returns?

Listen for connectivity changes and trigger a refresh when a network connection becomes available.

Use request-level error handling and prevent duplicate refresh operations.

For important data, refresh when the application resumes or when the user explicitly requests an update.

Can Flutter apps work without an internet connection?

Yes. Flutter applications can provide offline functionality by storing relevant data locally.

You can use SQLite, Drift, Hive CE, or other suitable storage solutions to display cached content and preserve user changes.

Features that require remote services will still need an appropriate online or synchronization strategy.

How do I handle network connectivity changes using GetX?

Create a GetX controller that listens to connectivity_plus and stores the reported network state in an RxBool.

Use Obx to update the UI when connectivity changes.

Register the controller at the application level when several screens need access to the same connectivity state.

Conclusion

Handling network connectivity changes is an important part of building reliable Flutter applications.

The connectivity_plus package makes it possible to detect available network interfaces and respond when users switch between Wi-Fi, mobile data, and offline states.

However, network connectivity alone does not guarantee internet access or backend availability.

For a production-ready implementation, combine connectivity monitoring with proper API error handling, lifecycle-aware checks, safe retry strategies, and local data storage where appropriate.

By preserving useful content during temporary connection loss and refreshing data when connectivity returns, you can create Flutter applications that provide a smoother experience under real-world network conditions.

The most important principle is to treat connectivity detection as a signal, not a guarantee that a network request will succeed.