useOnlineStatus

Detect network status changes and handle offline/online transitions. Includes offline queue for syncing data when connection is restored.

Live Demo

Use DevTools Network tab to simulate offline mode and see the queue in action.

🔴

Offline

💬 Message Queue Demo

Try sending messages while offline. They'll be queued and synced when you're back online.

No messages yet

💡 Try This:

Open DevTools → Network tab → Set to "Offline"
Send some messages - they'll be queued
Go back "Online" - messages will auto-sync

Code Examples

Basic Online Status

import { useOnlineStatus } from "@uiblock/hooks";

export default function NetworkIndicator() {
  const { isOnline, wasOffline } = useOnlineStatus();

  return (
    <div>
      {!isOnline && (
        <div className="offline-banner">
          You are offline. Changes will be saved locally.
        </div>
      )}
      {wasOffline && (
        <div className="reconnected-banner">
          Connection restored! Syncing...
        </div>
      )}
    </div>
  );
}

With Network Information

import { useOnlineStatus } from "@uiblock/hooks";

export default function NetworkInfo() {
  const status = useOnlineStatus();

  return (
    <div>
      <p>Status: {status.isOnline ? 'Online' : 'Offline'}</p>
      {status.effectiveType && (
        <p>Connection: {status.effectiveType}</p>
      )}
      {status.downlink && (
        <p>Speed: {status.downlink} Mbps</p>
      )}
    </div>
  );
}

Offline Queue with Auto-Sync

import { useOfflineQueue } from "@uiblock/hooks";

export default function DataSync() {
  const { addToQueue, queueSize, isSyncing } = useOfflineQueue({
    onSync: async (data) => {
      // This runs automatically when back online
      await fetch('/api/sync', {
        method: 'POST',
        body: JSON.stringify(data)
      });
    },
    maxRetries: 3
  });

  const saveData = (data) => {
    addToQueue(data);
  };

  return (
    <div>
      <button onClick={() => saveData({ text: 'Hello' })}>
        Save
      </button>
      {queueSize > 0 && (
        <p>{queueSize} items pending sync</p>
      )}
      {isSyncing && <p>Syncing...</p>}
    </div>
  );
}

How It Works

useOnlineStatus

import { useState, useEffect } from 'react'

export function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine)
  const [wasOffline, setWasOffline] = useState(false)

  useEffect(() => {
    const handleOnline = () => {
      setIsOnline(true)
      setWasOffline(true)
      setTimeout(() => setWasOffline(false), 5000)
    }

    const handleOffline = () => {
      setIsOnline(false)
    }

    window.addEventListener('online', handleOnline)
    window.addEventListener('offline', handleOffline)

    return () => {
      window.removeEventListener('online', handleOnline)
      window.removeEventListener('offline', handleOffline)
    }
  }, [])

  return { isOnline, wasOffline }
}

useOfflineQueue

import { useState, useEffect } from 'react'
import { useOnlineStatus } from './useOnlineStatus'

export function useOfflineQueue({ onSync, maxRetries = 3 }) {
  const { isOnline, wasOffline } = useOnlineStatus()
  const [queue, setQueue] = useState([])
  const [isSyncing, setIsSyncing] = useState(false)

  // Load from localStorage
  useEffect(() => {
    const stored = localStorage.getItem('offline-queue')
    if (stored) setQueue(JSON.parse(stored))
  }, [])

  // Save to localStorage
  useEffect(() => {
    localStorage.setItem('offline-queue', JSON.stringify(queue))
  }, [queue])

  // Auto-sync when back online
  useEffect(() => {
    if (!isOnline || !wasOffline || queue.length === 0) return

    const sync = async () => {
      setIsSyncing(true)
      for (const item of queue) {
        try {
          await onSync(item.data)
          removeFromQueue(item.id)
        } catch (error) {
          // Handle retry logic
        }
      }
      setIsSyncing(false)
    }

    sync()
  }, [isOnline, wasOffline])

  const addToQueue = (data) => {
    const item = { id: Date.now(), data, retries: 0 }
    setQueue(prev => [...prev, item])
  }

  return { queue, addToQueue, isSyncing }
}

API Reference

useOnlineStatus

Returns

isOnline: boolean - Current online status
wasOffline: boolean - True for 5s after reconnecting
downlink: number - Download speed in Mbps (if available)
effectiveType: string - Connection type (4g, 3g, 2g, slow-2g)
rtt: number - Round-trip time in ms
saveData: boolean - Data saver mode enabled

useOfflineQueue

Parameters

onSync: (item) => Promise - Function to sync queued items
maxRetries: number - Max retry attempts (default: 3)
storageKey: string - localStorage key (default: 'offline-queue')

Returns

queue: Array - Current queue items
addToQueue: (data) => string - Add item, returns ID
removeFromQueue: (id) => void - Remove specific item
clearQueue: () => void - Clear all items
isSyncing: boolean - Currently syncing
queueSize: number - Number of items in queue

💡 Use Cases

Offline-first applications
Form submissions that work offline
Chat applications with message queuing
Analytics tracking during poor connectivity
E-commerce cart sync
Progressive Web Apps (PWAs)
Real-time collaboration tools
Mobile apps with intermittent connectivity