unplugged

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 (

Status: {isOffline ? 'Offline' : 'Online'}

{lastChanged && (

Last changed: {lastChanged.toLocaleTimeString()}

)} {duration > 0 && (

Duration: {Math.floor(duration / 1000)} seconds

)}

); } \`\`\`

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 (

{isFromCache &&

Showing cached data

}

{data.name}

{data.email}

Refresh

); } \`\`\`

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}))} >

<button type="submit">Send Message</button> </OfflineForm> ); } \`\`\` ## 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<T>( url: string, options?: UseOfflineDataOptions<T> ): UseOfflineDataResult<T>; interface UseOfflineDataOptions<T> { initialData?: T; autoFetch?: boolean; cacheExpiry?: number | null; fetchOptions?: RequestInit; skip?: boolean; } interface UseOfflineDataResult<T> { data: T | null; loading: boolean; error: Error | null; isFromCache: boolean; refetch: () => Promise<void>; 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: <T>(url: string, options?: RequestInit & CacheOptions) => Promise<T>, getCachedData: <T>(key: string) => CacheEntry<T> | null, setCachedData: <T>(key: string, data: T, expiry: number | null) => void, clearCache: (keyPattern?: string) => void }; interface CacheOptions { expiry?: number | null; keyPrefix?: string; } \`\`\` ## License MIT