Unplugged

A lightweight library for handling offline states in React applications.

Features

• 🔌 Detect network connectivity changes
• 💾 Cache data for offline use
• 🚨 Show offline banners and notifications
• 📝 Queue form submissions when offline
• 🔄 Retry mechanisms for failed requests
• 🧩 Modular components and hooks for flexibility

Installation

```bash npm install unplugged

or

yarn add unplugged ```

Quick Start

Using the OfflineBoundary Component

```jsx import { OfflineBoundary } from 'unplugged';

function App() { return ( <OfflineBoundary showBanner={true} cacheContent={true} onOfflineChange={(isOffline) => console.log('Offline status:', isOffline)} > ); } ```

Using the useOffline Hook

```jsx import { useOffline } from 'unplugged';

function NetworkStatus() { const { isOffline, lastChanged, duration, wasNeverOnline } = useOffline();

return (

Fetching Data with Offline Support

```jsx import { useOfflineData } from 'react-offline-aware';

function UserProfile({ userId }) { const { data, loading, error, isFromCache, refetch, offlineState } = useOfflineData(/api/users/${userId}, { cacheExpiry: 60 _ 60 _ 1000, // 1 hour });

if (loading) return Loading...; if (error) return Error: {error.message};

return (

Offline-Aware Forms

```jsx import { OfflineForm } from 'react-offline-aware';

function ContactForm() { return ( <OfflineForm action="/api/contact" method="POST" onSuccess={(data) => alert('Message sent!')} onError={(error) => console.error('Error:', error)} onQueue={(id) => alert(Your message will be sent when you're back online (ID: ${id}))} > Send Message ); } ```

API Reference

Hooks

useOffline

```tsx function useOffline(options?: UseOfflineOptions): OfflineState;

interface UseOfflineOptions { isOnlineCheck?: () => boolean; pollingInterval?: number; }

interface OfflineState { isOffline: boolean; lastChanged: Date | null; duration: number; wasNeverOnline: boolean; } ```

useOfflineData

```tsx function useOfflineData( url: string, options?: UseOfflineDataOptions ): UseOfflineDataResult;

interface UseOfflineDataOptions { initialData?: T; autoFetch?: boolean; cacheExpiry?: number | null; fetchOptions?: RequestInit; skip?: boolean; }

interface UseOfflineDataResult { data: T | null; loading: boolean; error: Error | null; isFromCache: boolean; refetch: () => Promise; offlineState: OfflineState; } ```

Components

OfflineBoundary

```tsx function OfflineBoundary(props: OfflineBoundaryProps): JSX.Element;

interface OfflineBoundaryProps extends UseOfflineOptions { children: ReactNode; fallback?: ReactNode; showBanner?: boolean; cacheContent?: boolean; onOfflineChange?: (isOffline: boolean) => void; } ```

OfflineBanner

```tsx function OfflineBanner(props: OfflineBannerProps): JSX.Element | null;

interface OfflineBannerProps { offlineState: OfflineState; message?: string; className?: string; showRetry?: boolean; onRetry?: () => void; } ```

OfflineForm

```tsx function OfflineForm(props: OfflineFormProps): JSX.Element;

interface OfflineFormProps { children: React.ReactNode; action: string; method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; transformData?: (formData: FormData) => any; onSuccess?: (data: any) => void; onError?: (error: Error) => void; onQueue?: (queueId: string) => void; queueStorageKey?: string; [key: string]: any; } ```

Utilities

offlineCacheApi

```tsx const offlineCacheApi = { fetchWithCache: (url: string, options?: RequestInit & CacheOptions) => Promise, getCachedData: (key: string) => CacheEntry | null, setCachedData: (key: string, data: T, expiry: number | null) => void, clearCache: (keyPattern?: string) => void };

interface CacheOptions { expiry?: number | null; keyPrefix?: string; } ```

License

MIT