React Native Network State (Android 10+ / iOS 12+)

A high-performance React Native library for tracking network state using modern Android APIs (API 29+) and iOS NWPathMonitor (iOS 12+). This library provides accurate network state information by leveraging the latest platform APIs instead of deprecated methods used by older libraries.

🚀 Features

• Modern APIs: Android 10+ NetworkCapabilities, iOS 12+ NWPathMonitor
• Real-time monitoring with automatic foreground refresh
• Works with Old & New Architecture (TurboModules/Fabric)
• Detailed info and capabilities (coverage varies by platform)
• Simple React Hook + TypeScript types

📱 Why

Use modern platform APIs for accurate, real-time network state on Android 10+ and iOS 12+.

📋 Requirements

• React Native 0.71+
• Android: Android 10+ (API level 29+)
• iOS: iOS 12.0+

🛠 Installation

npm install @bear-block/network-state
# or
yarn add @bear-block/network-state

Setup

Autolinking handles configuration.

Android

• ✅ Permissions are automatically added to your app
• ✅ Requires Android 10+ (API 29+)
• ✅ Supports both Old Architecture and New Architecture (TurboModules)

iOS

• ✅ Frameworks are automatically linked (Network.framework)
• ✅ Requires iOS 12.0+
• ✅ Supports both Old Architecture and New Architecture (TurboModules/Fabric)

Note: All permissions and frameworks are automatically configured via autolinking. No manual setup required.

📖 Usage

Basic Usage

import { useNetworkState, NetworkType } from '@bear-block/network-state';

function MyComponent() {
  const { networkState, isListening, startListening, stopListening } = useNetworkState();

  useEffect(() => {
    if (networkState) {
      console.log('Network type:', networkState.type);
      console.log('Is connected:', networkState.isConnected);
      console.log('Internet reachable:', networkState.isInternetReachable);
    }
  }, [networkState]);

  return (
    <View>
      <Text>Network: {networkState?.type || 'Unknown'}</Text>
      <Text>Connected: {networkState?.isConnected ? 'Yes' : 'No'}</Text>
      <Button title="Start Listening" onPress={startListening} />
      <Button title="Stop Listening" onPress={stopListening} />
    </View>
  );
}

Advanced Usage

import { useNetworkState, NetworkType } from '@bear-block/network-state';

function AdvancedComponent() {
  const {
    networkState: current,
    isNetworkTypeAvailable,
    getNetworkStrength,
    isNetworkExpensive,
    isNetworkMetered,
    getWifiDetails,
    getNetworkCapabilities
  } = useNetworkState({ autoStart: true });

  const checkNetworkCapabilities = async () => {
    // Check if WiFi is available
    const wifiAvailable = await isNetworkTypeAvailable(NetworkType.WIFI);
    
    // Get network strength
    const strength = await getNetworkStrength();
    
    // Check if network is expensive (mobile data)
    const expensive = await isNetworkExpensive();
    
    // Get WiFi details
    const wifiDetails = await getWifiDetails();
    if (wifiDetails) {
      console.log('SSID:', wifiDetails.ssid);
      console.log('Signal strength:', wifiDetails.strength);
      console.log('Frequency:', wifiDetails.frequency);
    }
    
    // Get network capabilities
    const capabilities = await getNetworkCapabilities();
    if (capabilities) {
      console.log('Has WiFi transport:', capabilities.hasTransportWifi);
      console.log('Has internet capability:', capabilities.hasCapabilityInternet);
    }
  };

  return (
    <View>
      {/* Your UI components */}
    </View>
  );
}

Direct API Usage

import { networkState, NetworkType } from '@bear-block/network-state';

// Get current network state
const state = await networkState.getNetworkState();

// Check specific network types
const wifiConnected = await networkState.isConnectedToWifi();
const cellularConnected = await networkState.isConnectedToCellular();

// Check network availability and properties
const wifiAvailable = await networkState.isNetworkTypeAvailable(NetworkType.WIFI);
const strength = await networkState.getNetworkStrength();
const isExpensive = await networkState.isNetworkExpensive();
const isMetered = await networkState.isNetworkMetered();
const isReachable = await networkState.isInternetReachable();

// Get detailed information
const wifiDetails = await networkState.getWifiDetails();
const capabilities = await networkState.getNetworkCapabilities();

// Start/stop listening
networkState.startListening();
networkState.stopListening();

// Force refresh (useful when app comes to foreground)
networkState.forceRefresh();

🔧 API Reference

useNetworkState Hook

const {
  networkState,           // Current network state
  isListening,           // Whether listening is active
  startListening,        // Start listening to changes
  stopListening,         // Stop listening to changes
  refresh,               // Manually refresh state
  isNetworkTypeAvailable, // Check if network type is available
  getNetworkStrength,    // Get network signal strength
  isNetworkExpensive,    // Check if network is expensive
  isNetworkMetered,      // Check if network is metered
  isConnectedToWifi,     // Check WiFi connection
  isConnectedToCellular, // Check cellular connection
  isInternetReachable,   // Check internet reachability
  getWifiDetails,        // Get WiFi details
  getNetworkCapabilities // Get network capabilities
} = useNetworkState(options);

// Note: forceRefresh() is automatically called when app returns to foreground
// No need to call it manually in most cases

NetworkState Interface

interface NetworkState {
  isConnected: boolean;
  isInternetReachable: boolean;
  type: NetworkType;
  isExpensive: boolean;
  isMetered: boolean;
  details?: NetworkDetails;
}

interface NetworkDetails {
  ssid?: string;            // WiFi network name (Android)
  bssid?: string;           // WiFi BSSID (Android)
  strength?: number;        // Signal strength (Android; iOS may be unavailable and return -1)
  frequency?: number;       // WiFi frequency in MHz (Android)
  linkSpeed?: number;       // WiFi link speed (Android)
  capabilities?: NetworkCapabilities; // Both; field coverage varies by platform
}

NetworkType Enum

enum NetworkType {
  NONE = 'none',
  UNKNOWN = 'unknown',
  WIFI = 'wifi',                    // Android & iOS
  CELLULAR = 'cellular',            // Android & iOS
  ETHERNET = 'ethernet',            // Android & iOS (iOS via NWPath)
  BLUETOOTH = 'bluetooth',          // Android (iOS transport not exposed via public APIs)
  VPN = 'vpn',                      // Android (iOS transport not exposed via public APIs)
  WIFI_AWARE = 'wifi_aware',        // Android (API 26+)
  LOWPAN = 'lowpan'                 // Android (API 27+)
}

Platform Support by API

• useNetworkState hook: Android & iOS
• getNetworkState(): Android & iOS
• start/stop listening: Android & iOS
• refresh(): Android & iOS (manually refresh network state)
• isNetworkTypeAvailable(): Android & iOS (types available differ per platform)
• getNetworkStrength(): Android (iOS returns -1)
• isNetworkExpensive(): Android & iOS (treated as true on cellular)
• isNetworkMetered(): Android & iOS (treated as true on cellular)
• isConnectedToWifi()/isConnectedToCellular(): Android & iOS
• isInternetReachable(): Android & iOS
• getWifiDetails(): Android (may be null on iOS)
• getNetworkCapabilities(): Android & iOS (fields coverage varies)
• forceRefresh(): Android & iOS (automatically called on foreground, can be called manually)

🧪 Example

cd example && yarn install
yarn android # or yarn ios

🔄 Background/Foreground Handling

The library automatically handles app lifecycle changes to ensure network state accuracy:

Automatic State Refresh

• ✅ Background → Foreground: Automatically refreshes network state when app returns to foreground
• ✅ Network Changes in Background: Native callbacks continue working in background
• ✅ State Consistency: UI always shows current network state when app becomes active
• ✅ Zero Configuration: Works automatically without any setup

How It Works

1. App goes to background: Network monitoring continues at native level
2. Network changes in background: Native callbacks detect changes
3. App returns to foreground: AppState listener triggers automatic refresh
4. State updates: Both native and React state are refreshed automatically

Example Usage

const { networkState, isListening } = useNetworkState({ autoStart: true });

// No additional code needed - background/foreground handling is automatic!
// When user returns to app, network state will be automatically refreshed

🔍 How It Works

Android Implementation (Summary)

1. Network Capabilities API: Uses NetworkCapabilities to detect network type and capabilities
2. Network Callbacks: Implements ConnectivityManager.NetworkCallback for real-time updates
3. Modern Permissions: Handles Android 10+ permission requirements properly
4. Efficient Monitoring: Only listens when needed and provides accurate state information
5. App Lifecycle: Handles background/foreground transitions with automatic state refresh

iOS Implementation (Summary)

1. NWPathMonitor: Uses NWPathMonitor for real-time network state monitoring
2. Network Framework: Leverages iOS 12+ Network framework for reliable detection
3. Interface Detection: Detects WiFi, Cellular, Ethernet, and other interface types
4. Event Emission: Emits network state changes to React Native via events
5. App Lifecycle: Handles background/foreground transitions with automatic state refresh

🤝 Contributing

PRs welcome.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with modern Android/iOS APIs.

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include your React Native version and platform details

Note: Designed for Android 10+ and iOS 12+. For older OS versions, consider other libraries.