@sonardigital/network-status

A React package for detecting network status, connection quality, and slow/failing connections.

Features

• 🌐 Online/offline detection
• 📶 Connection quality assessment (excellent, good, fair, poor, offline)
• 🐢 Slow connection detection with configurable thresholds
• 📊 Network Information API support (effectiveType, downlink, RTT)
• 💾 Data saver mode detection
• ⚛️ React Context + Hook pattern

Installation

npm install @sonardigital/network

Usage

With Provider (Recommended)

import {
	NetworkStatusProvider,
	useNetworkStatus,
	useNetworkStatusContext,
} from '@sonardigital/network-status';

function App() {
	const methods = useNetworkStatus({
		slowRttThreshold: 500,
		slowDownlinkThreshold: 1,
	});

	return (
		<NetworkStatusProvider methods={methods}>
			<YourApp />
		</NetworkStatusProvider>
	);
}

// Use in any child component
function ConnectionIndicator() {
	const { isOnline, isSlow, connectionQuality } = useNetworkStatusContext();

	if (!isOnline) return <div>You are offline</div>;
	if (isSlow) return <div>Slow connection detected</div>;

	return <div>Connection: {connectionQuality}</div>;
}

Standalone Hook

import { useNetworkStatus } from '@sonardigital/network-status';

function MyComponent() {
	const { isOnline, isSlow, connectionQuality, effectiveType, downlink, rtt, saveData, lastChanged } =
		useNetworkStatus({
			slowRttThreshold: 500,
			slowDownlinkThreshold: 1,
		});

	return (
		<div>
			<p>Online: {isOnline ? 'Yes' : 'No'}</p>
			<p>Quality: {connectionQuality}</p>
			<p>Slow: {isSlow ? 'Yes' : 'No'}</p>
			{effectiveType && <p>Type: {effectiveType}</p>}
			{downlink && <p>Speed: {downlink} Mbps</p>}
			{rtt && <p>Latency: {rtt}ms</p>}
		</div>
	);
}

API

NetworkStatusContextType

| Property | Type | Description | | ------------------- | ------------------------------------------- | ----------------------------------------------------------------------------- | | isOnline | boolean | Whether the browser is online | | isSlow | boolean | Whether the connection is considered slow | | connectionQuality | ConnectionQuality | Quality assessment: 'excellent', 'good', 'fair', 'poor', 'offline', 'unknown' | | effectiveType | '4g' \| '3g' \| '2g' \| 'slow-2g' \| null | Effective connection type | | downlink | number \| null | Downlink speed in Mbps | | rtt | number \| null | Round-trip time in ms | | saveData | boolean | Whether data saver mode is enabled | | lastChanged | Date \| null | Timestamp of last status change |

UseNetworkStatusProps

| Prop | Type | Default | Description | | ----------------------- | -------- | ------- | ----------------------------------------------------- | | slowRttThreshold | number | 500 | RTT threshold (ms) to consider connection slow | | slowDownlinkThreshold | number | 1 | Downlink threshold (Mbps) to consider connection slow |

NetworkStatusProviderProps

| Prop | Type | Description | | ---------- | ------------------------------------- | ------------------------------------ | | methods | ReturnType<typeof useNetworkStatus> | Network status methods from the hook | | children | React.ReactNode | Child components |

Browser Support

The Network Information API is supported in Chromium-based browsers. For unsupported browsers, the package falls back to basic online/offline detection.