Repository files navigation

React Native Network Info API for Android, iOS, macOS, Windows & Web. It allows you to get information on:

• Connection type
• Connection quality

Install the library using either Yarn:

yarn add @react-native-community/netinfo

or npm:

npm install --save @react-native-community/netinfo

Linking the package manually is not required anymore withAutolinking.

• iOS Platform:

  $ npx pod-install # CocoaPods on iOS needs this extra step

• Android Platform with AndroidX:

  Modify yourandroid/build.gradle configuration:

  buildscript {  ext {    buildToolsVersion = "xx.yy.zz"    minSdkVersion = xyz    compileSdkVersion = xyz    targetSdkVersion = xyz  }

• macOS Platform:

  Autolinking is not yet available on macOS. See theManual linking steps for macOS below.

• Windows Platform:

  Autolinking automatically works on RNW >= 0.63.

• react-native-windows 0.63 or newer
• MSVC build tools v142 (included in Visual Studio 2019) or newer
• x86, x64, or arm64 are supported, arm (32-bit) is not supported

To use this library you need to ensure you are using the correct version of React Native.We support react-native 0.60+ with auto-linking.

If you are using a version of React Native that is lower than 0.60 check older versions of this README for details,but no support will be provided.

The web implementation heavily depends on theNetwork Information API which is still an is an experimental technology and thus it's not supported in every browser.If this API is not available the library will safely fallback to the oldonLine property and return basic connection information.

AbortController is used to cancel network requests, and may not be available on Internet Explorer, though it is available on Edgehttps://caniuse.com/abortcontroller

Node v16 is the minimum required node version -AbortController is only present in stable versions of node from v16 on

This module was created when the NetInfo was split out from the core of React Native. To migrate to this module you need to follow the installation instructions above and then change your imports from:

import{NetInfo}from"react-native";

to:

importNetInfofrom"@react-native-community/netinfo";

Note that the API was updated after it was extracted from NetInfo to support some new features, however, the previous API is still available and works with no updates to your code.

Internally this library has a network state manager class to handle all the functionality and state. This library provides two options for instantiating the class:

1. you can use global library functions which taps into a global singleton instance of the class
2. or you can create isolated instances of the class to tap into, each being separately configured

Subscribe to network state updates:

import{addEventListener}from"@react-native-community/netinfo";// Subscribeconstunsubscribe=addEventListener(state=>{console.log("Connection type",state.type);console.log("Is connected?",state.isConnected);});// Unsubscribeunsubscribe();

Get the network state once:

import{fetch}from"@react-native-community/netinfo";fetch().then(state=>{console.log("Connection type",state.type);console.log("Is connected?",state.isConnected);});

Get network state updates from the global instance via a react hook:

import{useNetInfo}from"@react-native-community/netinfo";const{ type, isConnected}=useNetInfo();

Use an isolated instance of the network manager:

import{useNetInfoInstance}from"@react-native-community/netinfo";const{netInfo:{ type, isConnected}, refresh}=useNetInfoInstance();

• Types:
  • NetInfoState
  • NetInfoStateType
  • NetInfoCellularGeneration
• Global instance methods:
  • fetch()
  • refresh()
  • addEventListener()
  • useNetInfo()
• Isolated instance:
  • useNetInfoInstance()

Describes the current state of the network. It is an object with these properties:

Thedetails value depends on thetype value.

details isnull.

details has these properties:

* RequireswiFiControl capability in appxmanifest. Without it, these values will be null.

details has these properties:

details has these properties:

Describes the current type of network connection. It is an enum with these possible values:

Describes the current generation of thecellular connection. It is an enum with these possible values:

The configuration options for the library.

Please note the difference between global and isolated usage describedhere

Configures the library with the given configuration. You only need to supply the properties which you want to change from the default values.

Note that calling this will stop all previously added listeners from being called again. It is best to call this right when your application is started to avoid issues.

Example:

NetInfo.configure({reachabilityUrl:'https://clients3.google.com/generate_204',reachabilityTest:async(response)=>response.status===204,reachabilityLongTimeout:60*1000,// 60sreachabilityShortTimeout:5*1000,// 5sreachabilityRequestTimeout:15*1000,// 15sreachabilityShouldRun:()=>true,shouldFetchWiFiSSID:true,// met iOS requirements to get SSID. Will leak memory if set to true without meeting requirements.useNativeReachability:false});

Subscribe to connection information. The callback is called with a parameter of typeNetInfoState whenever the connection state changes. Your listener will be called with the latest information soon after you subscribe and then with any subsequent changes afterwards. You should not assume that the listener is called in the same way across devices or platforms.

Example:

// Subscribeconstunsubscribe=NetInfo.addEventListener(state=>{console.log("Connection type",state.type);console.log("Is connected?",state.isConnected);});// Unsubscribeunsubscribe();

AReact Hook which can be used to get access to the latest state from the global instance. It returns a hook with theNetInfoState type.

Example:

import{useNetInfo}from"@react-native-community/netinfo";constYourComponent=()=>{constnetInfo=useNetInfo();return(<View><Text>Type:{netInfo.type}</Text><Text>Is Connected?{netInfo.isConnected?.toString()}</Text></View>);};

You can optionally send configuration when setting up the hook. Note that configuration is global for the library, so you shouldn't send different configuration for different hooks. It is instead recommended that you calledNetInfo.configure() once when your project starts. The hook option is only provided as a convinience.

constYourComponent=()=>{constnetInfo=useNetInfo({reachabilityUrl:'https://clients3.google.com/generate_204',reachabilityTest:async(response)=>response.status===204,reachabilityLongTimeout:60*1000,// 60sreachabilityShortTimeout:5*1000,// 5sreachabilityRequestTimeout:15*1000,// 15sreachabilityShouldRun:()=>true,shouldFetchWiFiSSID:true,// met iOS requirements to get SSIDuseNativeReachability:false});// ...};

Returns aPromise that resolves to aNetInfoState object.

Example:

NetInfo.fetch().then(state=>{console.log("Connection type",state.type);console.log("Is connected?",state.isConnected);});

You can optionally send aninterface string so thePromise resolves to aNetInfoState from theNetInfoStateType indicated ininterface argument.

NetInfo.fetch("wifi").then(state=>{console.log("SSID",state.details.ssid);console.log("BSSID",state.details.bssid);console.log("Is connected?",state.isConnected);});

Updates NetInfo's internal state, then returns aPromise that resolves to aNetInfoState object. This is similar tofetch(), but really only useful on platforms that do not supply internet reachability natively. For example, you can use it to immediately re-run an internet reachability test if a network request fails unexpectedly.

Example:

NetInfo.refresh().then(state=>{console.log("Connection type",state.type);console.log("Is connected?",state.isConnected);});

This will also update subscribers usingaddEventListener and/oruseNetInfo.

Please note the difference between global and isolated usage describedhere

AReact Hook which can be used to create and manage an isolated instance of a network manager class. It returns arefresh function and the currentNetInfoState.

Example:

import{useNetInfoInstance}from"@react-native-community/netinfo";constYourComponent=()=>{const{netInfo, refresh}=useNetInfoInstance();return(<View><Text>Type:{netInfo.type}</Text><Text>Is Connected?{netInfo.isConnected?.toString()}</Text></View>);};

isPaused: You can also pause the hooks internal network checks by passing a boolean valuetrue as the first argument.

configuration: You can optionally send configuration as the second argument when setting up the hook. Note that configuration is local to the instance managed by this hook and has no relation to the configuration passed to other functionsconfigure() oruseNetInfo();

import{useNetInfoInstance}from"@react-native-community/netinfo";constYourComponent=()=>{constisPaused=false;constconfig={reachabilityUrl:'https://clients3.google.com/generate_204',reachabilityTest:async(response)=>response.status===204,reachabilityLongTimeout:60*1000,// 60sreachabilityShortTimeout:5*1000,// 5sreachabilityRequestTimeout:15*1000,// 15sreachabilityShouldRun:()=>true,shouldFetchWiFiSSID:true,// met iOS requirements to get SSIDuseNativeReachability:false}const{ netInfo}=useNetInfoInstance(isPaused,config);//...

If you do not have a Jest Setup file configured, you should add the following to your Jest settings and create thejest.setup.js file in project root:

setupFiles:['<rootDir>/jest.setup.js']

You should then add the following to your Jest setup file to mock the NetInfo Native Module:

importmockRNCNetInfofrom'@react-native-community/netinfo/jest/netinfo-mock.js';jest.mock('@react-native-community/netinfo',()=>mockRNCNetInfo);

There is aknownissue with the iOS Simulator which causes it to not receive network change notifications correctly when the host machine disconnects and then connects to Wifi. If you are having issues with iOS then please test on an actual device before reporting any bugs.

The SCNetworkReachability API used in iOS does not send events to the app in the background, so switching from one Wi-Fi network to another when your App was in background will not send an event and your network state will be out of sync with device state. To be sure you have up to date status when your app is in foreground again, you should re-fetch state each time when App comes to foreground, something like this:

useEffect(()=>{constsubAppState=AppState.addEventListener("change",async(nextAppState)=>{if(IS_IOS_DEVICE&&nextAppState=='active'){letnewNetInfo=awaitNativeModules.RNCNetInfo.getCurrentState('wifi');//your code here}});constunsubNetState=NetInfo.addEventListener(state=>{//your code here});return()=>{if(subAppState){subAppState.remove();}unsubNetState();};},[]);

• Mike Hardy

• Matt Oakes -Freelance React Native Developer
• Mike Diarmid -Invertase

Please see thecontributing guide.

The library is released under the MIT license. For more information seeLICENSE.