React Network Status Notification (React-nsn)

Component | Example :-------------------------:|:-------------------------: |

1. Network status hook useOnlineStatus()
   • app online network status
   • status time info
   • network information
   • custom polling with exponential backoff
   • onStatusChange callback
   • checkNow() for manual connectivity checks
   • custom pollingFn for your own health-check logic
2. Notification component <OnlineStatusNotification/>
3. Headless mode — use only the hook without the notification UI (~1.4KB gzipped)

Table of Contents

• Online demo
• How to use
• Headless mode
• Documentation
• Compatibility
• License

Online demo

https://amrahmeda.github.io/react-nsn

Getting Started

npm

npm i react-nsn

How to use

add <OnlineStatusNotification/> to your app, preferably at root level.

import { OnlineStatusNotification, useOnlineStatus } from 'react-nsn'

function App() {
  const {
    attributes,
    isOnline,
    time: { difference, since },
    connectionInfo,
  } = useOnlineStatus()

  // logs current connection info
  console.log(connectionInfo)

  const statusText = isOnline ? `online` : `offline`

  return (
    <div>
      <h1>{`App is ${statusText}`}</h1>
      <h1>{`the app is ${statusText} since: ${since}`}</h1>
      <h1>{`difference in time since the component was ${statusText}: ${difference}`}</h1>
      <OnlineStatusNotification darkMode={true} {...attributes} />
    </div>
  )
}

Headless mode

If you only need the hook without the notification component, import from react-nsn/headless for a smaller bundle (~1.4KB gzipped vs ~10.7KB):

import { useOnlineStatus } from 'react-nsn/headless'

function App() {
  const { isOnline, checkNow } = useOnlineStatus({
    onStatusChange: (online) => console.log('Status changed:', online),
  })

  return <p>{isOnline ? 'Online' : 'Offline'}</p>
}

Documentation

<OnlineStatusNotification/> has the following props:

| Name | Type | Default | Description | |------------ |--------------- |--------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | className | string | | additional CSS class name(s) for the notification container | | darkMode | boolean | false | toggle dark mode | | destroyOnClose | boolean | true | remove notification from DOM when it hides | | duration | number | 4500ms | duration of the notification when it pops up on screen before hiding back | | eventsCallback.onRefreshClick | function | | callback triggered when refresh is clicked during offline status | | eventsCallback.onCloseClick | function | | callback triggered when close button is clicked | | position | string | bottomLeft | topLeft topRight topCenter bottomLeft bottomRight bottomCenter | | statusText.online | string | Your internet connection was restored. | custom online text | | statusText.offline | string | You are currently offline. | custom offline text | | style | CSSProperties | | inline styles for the notification container |

The component exposes an imperative handle via ref with openStatus() and dismiss() methods.

useOnlineStatus hook has the following arguments:

| Name | Type | Default | Description | |------------ |--------------- |--------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pollingUrl | string | https://www.gstatic.com/generate_204 | url used to perform polling | | pollingDuration | number | 12000ms | base delay between requests (backs off exponentially when offline, capped at 60s) | | pollingFn | () => Promise<boolean> | | custom connectivity check — return true if online, false if offline. Overrides pollingUrl | | onStatusChange | (isOnline: boolean) => void | | callback fired when status changes (skips initial render) |

useOnlineStatus hook offers the following:

| Name | Type | Description | |------------ |--------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isOnline | boolean | app online status | | isOffline | boolean | app offline status | | checkNow | () => Promise<void> | manually trigger a connectivity check | | time.since | Date | date of the last status change | | time.difference | string | human-readable time since last status change | | connectionInfo | NetworkInformation \| null | Network Information API data (connection type, effective type, etc.) | | attributes | object | pass directly to <OnlineStatusNotification/> as props |

Next.js / Server Components

This library relies on browser APIs (window, navigator) and React client hooks, so it is client-side only. If you are using Next.js App Router, wrap your usage in a client component:

'use client'

import { OnlineStatusNotification, useOnlineStatus } from 'react-nsn'

export default function NetworkStatus() {
  const { attributes } = useOnlineStatus()
  return <OnlineStatusNotification {...attributes} />
}

Compatibility

| IE / Edge | Firefox | Chrome | Safari | Electron | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | IE11, Edge | latest version | latest version | latest version | latest version |

License

React-nsn is released under the MIT license.