0
# Network State Management
1

2
Core network information functionality for retrieving connection status, connection type, and internet reachability. Supports both one-time queries and continuous monitoring with a global singleton pattern.
3

4
## Capabilities
5

6
### Fetch Network State
7

8
Returns a Promise that resolves to the current network state information.
9

10
```typescript { .api }
11
/**
12
 * Returns a Promise that resolves to a NetInfoState object.
13
 * This function operates on the global singleton instance configured using configure()
14
 * @param requestedInterface - interface from which to obtain the information
15
 * @returns A Promise which contains the current connection state
16
 */
17
function fetch(requestedInterface?: string): Promise<NetInfoState>;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { fetch } from "@react-native-community/netinfo";
24

25
// Get current network state
26
const state = await fetch();
27
console.log("Connection type:", state.type);
28
console.log("Is connected:", state.isConnected);
29
console.log("Is internet reachable:", state.isInternetReachable);
30

31
// Request specific interface (optional)
32
const wifiState = await fetch("wifi");
33
```
34

35
### Refresh Network State
36

37
Force-refreshes the internal state of the global singleton and returns updated network information.
38

39
```typescript { .api }
40
/**
41
 * Force-refreshes the internal state of the global singleton managed by this library.
42
 * @returns A Promise which contains the updated connection state
43
 */
44
function refresh(): Promise<NetInfoState>;
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { refresh } from "@react-native-community/netinfo";
51

52
// Force refresh network state
53
const freshState = await refresh();
54
console.log("Updated connection type:", freshState.type);
55
```
56

57
### Event Listener
58

59
Subscribe to network state changes. The callback is called whenever the connection state changes.
60

61
```typescript { .api }
62
/**
63
 * Subscribe to the global singleton's connection information. The callback is called with a parameter of type
64
 * NetInfoState whenever the connection state changes. Your listener
65
 * will be called with the latest information soon after you subscribe and then with any
66
 * subsequent changes afterwards. You should not assume that the listener is called in the same
67
 * way across devices or platforms.
68
 * @param listener - The listener which is called when the network state changes
69
 * @returns A function which can be called to unsubscribe
70
 */
71
function addEventListener(listener: NetInfoChangeHandler): NetInfoSubscription;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { addEventListener } from "@react-native-community/netinfo";
78

79
// Subscribe to network changes
80
const unsubscribe = addEventListener(state => {
81
  console.log("Network changed:", state.type);
82
  
83
  if (state.isConnected) {
84
    console.log("Connected to:", state.type);
85
    if (state.type === 'wifi' && state.details) {
86
      console.log("WiFi SSID:", state.details.ssid);
87
    }
88
  } else {
89
    console.log("Disconnected");
90
  }
91
});
92

93
// Clean up subscription
94
unsubscribe();
95
```
96

97
### Configuration
98

99
Configures the library with global configuration options. Note that calling this will stop all previously added listeners from being called again.
100

101
```typescript { .api }
102
/**
103
 * Configures the library with the given configuration. Note that calling this will stop all
104
 * previously added listeners from being called again. It is best to call this right when your
105
 * application is started to avoid issues. The configuration sets up a global singleton instance.
106
 * @param configuration - The new configuration to set
107
 */
108
function configure(configuration: Partial<NetInfoConfiguration>): void;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { configure } from "@react-native-community/netinfo";
115

116
// Configure custom reachability testing
117
configure({
118
  reachabilityUrl: 'https://clients3.google.com/generate_204',
119
  reachabilityTest: async (response) => response.status === 204,
120
  reachabilityLongTimeout: 60 * 1000, // 60s
121
  reachabilityShortTimeout: 5 * 1000, // 5s
122
  reachabilityRequestTimeout: 15 * 1000, // 15s
123
  shouldFetchWiFiSSID: true, // iOS: requires meeting requirements
124
  useNativeReachability: false
125
});
126
```
127

128
## Network State Types
129

130
```typescript { .api }
131
interface NetInfoUnknownState {
132
  type: NetInfoStateType.unknown;
133
  isConnected: boolean | null;
134
  isInternetReachable: null;
135
  details: null;
136
  isWifiEnabled?: boolean;
137
}
138

139
type NetInfoNoConnectionState = {
140
  type: NetInfoStateType.none;
141
  isConnected: boolean;
142
  isInternetReachable: boolean;
143
  details: null;
144
  isWifiEnabled?: boolean;
145
};
146

147
type NetInfoCellularState = {
148
  type: NetInfoStateType.cellular;
149
  isConnected: boolean;
150
  isInternetReachable: boolean | null;
151
  details: {
152
    isConnectionExpensive: boolean;
153
    cellularGeneration: NetInfoCellularGeneration | null;
154
    carrier: string | null;
155
  };
156
  isWifiEnabled?: boolean;
157
};
158

159
type NetInfoWifiState = {
160
  type: NetInfoStateType.wifi;
161
  isConnected: boolean;
162
  isInternetReachable: boolean | null;
163
  details: {
164
    isConnectionExpensive: boolean;
165
    ssid: string | null;
166
    bssid: string | null;
167
    strength: number | null;
168
    ipAddress: string | null;
169
    subnet: string | null;
170
    frequency: number | null;
171
    linkSpeed: number | null;
172
    rxLinkSpeed: number | null;
173
    txLinkSpeed: number | null;
174
  };
175
  isWifiEnabled?: boolean;
176
};
177

178
type NetInfoBluetoothState = {
179
  type: NetInfoStateType.bluetooth;
180
  isConnected: boolean;
181
  isInternetReachable: boolean | null;
182
  details: {
183
    isConnectionExpensive: boolean;
184
  };
185
  isWifiEnabled?: boolean;
186
};
187

188
type NetInfoEthernetState = {
189
  type: NetInfoStateType.ethernet;
190
  isConnected: boolean;
191
  isInternetReachable: boolean | null;
192
  details: {
193
    isConnectionExpensive: boolean;
194
    ipAddress: string | null;
195
    subnet: string | null;
196
  };
197
  isWifiEnabled?: boolean;
198
};
199

200
type NetInfoWimaxState = {
201
  type: NetInfoStateType.wimax;
202
  isConnected: boolean;
203
  isInternetReachable: boolean | null;
204
  details: {
205
    isConnectionExpensive: boolean;
206
  };
207
  isWifiEnabled?: boolean;
208
};
209

210
type NetInfoVpnState = {
211
  type: NetInfoStateType.vpn;
212
  isConnected: boolean;
213
  isInternetReachable: boolean | null;
214
  details: {
215
    isConnectionExpensive: boolean;
216
  };
217
  isWifiEnabled?: boolean;
218
};
219

220
type NetInfoOtherState = {
221
  type: NetInfoStateType.other;
222
  isConnected: boolean;
223
  isInternetReachable: boolean | null;
224
  details: {
225
    isConnectionExpensive: boolean;
226
  };
227
  isWifiEnabled?: boolean;
228
};
229

230
type NetInfoDisconnectedStates = NetInfoUnknownState | NetInfoNoConnectionState;
231
type NetInfoConnectedStates = 
232
  | NetInfoCellularState 
233
  | NetInfoWifiState 
234
  | NetInfoBluetoothState 
235
  | NetInfoEthernetState 
236
  | NetInfoWimaxState 
237
  | NetInfoVpnState 
238
  | NetInfoOtherState;
239

240
type NetInfoState = NetInfoDisconnectedStates | NetInfoConnectedStates;
241

242
type NetInfoChangeHandler = (state: NetInfoState) => void;
243
type NetInfoSubscription = () => void;
244
```