network_aware_ui 0.1.0

A lightweight, reactive Flutter package to monitor network connectivity, verify internet reachability, and render customizable offline UI states.

network_aware_ui

A lightweight, reactive Flutter package that helps developers handle network connectivity, internet reachability, and offline UI states with minimal code.

Features

• Network Interface Detection: Identify Wi-Fi, cellular, Ethernet, VPN, Bluetooth, satellite, or disconnected states.
• Reachability Verification: Differentiates between physical interface connection and actual end-to-end internet access (detects captive portals, dead uplinks).
• Reactive State Stream: Clean stream and snapshot models (NetworkState, NetworkStatus, NetworkConnectionType).
• Declarative UI Components:
  • NetworkAwareBuilder: Conditionally render UI based on online/offline state.
  • NetworkAwareBanner: Animated non-intrusive banner overlay (top/bottom) that appears when offline and displays an optional "Back online" confirmation.
  • OfflineWidget: Configurable placeholder screen/card with retry action and automatic progress indicator.

Development Roadmap

• ✅ Phase 1 — Foundation: Package structure, state models (NetworkStatus, NetworkConnectionType, NetworkState), public API exports.
• ✅ Phase 2 — Connectivity Manager: connectivity_plus integration, interface change stream, lifecycle management.
• ✅ Phase 3 — Internet Reachability: Socket reachability probes, target fallback, timeout handling, caching and deduplication.
• ✅ Phase 4 — UI Components: Offline banner, network-aware builder, transitions and animations, offline widget.
• ✅ Phase 5 — Testing: Comprehensive unit, widget, transition, and mock network tests (77+ tests passing).
• ✅ Phase 6 — Platform Validation: Android, iOS, and macOS compatibility documentation and requirements.
• ✅ Phase 7 — Release: Interactive example application, pubspec configuration, flutter pub publish --dry-run verified.

Getting Started

Add network_aware_ui to your pubspec.yaml:

dependencies:
  network_aware_ui: ^0.1.0

Import the package:

import 'package:network_aware_ui/network_aware_ui.dart';

Platform Configuration

Android

Ensure internet permissions are present in your android/app/src/main/AndroidManifest.xml:

<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"/>
    ...
</manifest>

• Minimum Android SDK: API 21+ (Android 5.0 Lollipop).
• Gradle / AGP: Compatible with Java 11/17, AGP 8.x, Gradle 8.x.

iOS

• Minimum iOS version: iOS 12.0+.
• No additional Info.plist entries required for standard internet checks.

macOS

Ensure your app enables outgoing network client connections in both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<key>com.apple.security.network.client</key>
<true/>

Usage

1. Network-Aware Builder

Rebuild your widget tree reactively when connectivity or reachability changes:

NetworkAwareBuilder(
  builder: (context, state) {
    if (state.isOffline) {
      return const OfflineWidget();
    }
    return const HomeScreen();
  },
)

Or use dedicated builders with animated transitions:

NetworkAwareBuilder(
  animateTransitions: true,
  onlineBuilder: (context, state) => const HomeScreen(),
  offlineBuilder: (context, state) => const OfflineWidget(),
  checkingBuilder: (context, state) => const LoadingScreen(),
)

2. Network-Aware Banner

Wrap any screen with a non-intrusive banner overlay that slides down when offline:

NetworkAwareBanner(
  bannerPosition: BannerPosition.top,
  child: Scaffold(
    appBar: AppBar(title: const Text('My App')),
    body: const HomeScreen(),
  ),
)

3. Customizable Offline Placeholder

Display a styled offline placeholder with a retry button:

OfflineWidget(
  title: 'Connection Lost',
  message: 'Could not communicate with the server.',
  retryButtonText: 'Try Again',
  onRetry: () async {
    // Custom reload action, or omit to auto-trigger reachability check
    await fetchLatestData();
  },
)

4. Global NetworkAware Singleton

Listen to network state changes globally without widget context:

// Stream of state changes:
NetworkAware.instance.onStatusChanged.listen((state) {
  if (state.isOffline) {
    print('Device went offline');
  }
});

// Synchronous snapshot:
if (NetworkAware.instance.isOnline) {
  print('Device is online');
}

Example Application

Check out the example/ directory for a complete, runnable Flutter app showcasing all components and controls.

Author

Developed and maintained by Srinivasan (@srini16112).

License

MIT License. See LICENSE for details.