Offline banner

createBanner adds a small floating card to the page that follows the watcher. It is plain DOM, so it works in any framework, and it does not need an adapter.

import { createBanner } from '@net-watch/core/banner'
import { watcher } from './network'

const banner = createBanner(watcher, { slowText: 'Slow connection' })

// later, for example when your app unmounts
banner.destroy()

What it showsCopy Anchor Link

The banner stays hidden while everything is fine. It does not announce "online" when the page first loads. If the page loads while the user is already offline (or already poor with slowText set), the banner shows right away.

Without slowText, the slow state never appears. That keeps the default quiet: a poor connection is not a failure, and not every app wants to say so.

OptionsCopy Anchor Link

All options are optional.

createBanner(watcher, {
  offlineText: 'No connection. Changes will sync later.',
  onlineText: 'Connected again',
  slowText: 'Slow connection',
  position: 'top',
  hideAfter: 2000,
})

The handleCopy Anchor Link

createBanner returns an object with two methods:

• destroy() removes the banner element and unsubscribes from the watcher. Call it when your app or component goes away. The shared <style> element stays in the page, so other banners keep working.
• setTheme(theme) switches between 'auto', 'light' and 'dark' at runtime. Use it if your app has its own theme toggle.

const banner = createBanner(watcher)

themeToggle.addEventListener('change', () => {
  banner.setTheme(themeToggle.checked ? 'dark' : 'light')
})

Theming with CSS variablesCopy Anchor Link

The banner's colours are four CSS variables, set on the banner element for each state:

The banner has the class .netwatch-banner and three data attributes you can target:

Override the variables for one state with a single rule:

.netwatch-banner[data-state='offline'] {
  --netwatch-bg: #fff0f0;
  --netwatch-fg: #7a1f1f;
  --netwatch-accent: #d92d20;
}

.netwatch-banner[data-state='slow'] {
  --netwatch-icon: url('/icons/turtle.svg');
}

/* Only when the dark palette is forced */
.netwatch-banner[data-theme='dark'][data-state='offline'] {
  --netwatch-bg: #3a1212;
}

You can also restyle the card itself:

.netwatch-banner {
  max-width: 40rem;
  border-radius: 0;
  font-size: 16px;
}

The default styles use :where(), which gives them zero specificity. Any rule you write wins without !important, whatever order the stylesheets load in. The one exception is the hidden state: .netwatch-banner[hidden] uses display: none !important, so a display rule of yours cannot keep a hidden banner visible.

With theme: 'auto', the dark palette applies inside @media (prefers-color-scheme: dark). Your own rules still win over it.

AccessibilityCopy Anchor Link

The banner has role="status", a polite live region. Screen readers announce each text change without interrupting what the user is doing. The element is hidden with the hidden attribute when there is nothing to say, so it is not in the accessibility tree then.

The entrance animation is turned off for users who prefer reduced motion.

Use it in a frameworkCopy Anchor Link

The banner needs document, so create it after the component mounts and destroy it on cleanup. See SSR for why.

import { useEffect } from 'react'
import { createBanner } from '@net-watch/core/banner'
import { watcher } from './network'

export function OfflineBanner() {
  useEffect(() => {
    const banner = createBanner(watcher, { slowText: 'Slow connection' })
    return () => banner.destroy()
  }, [])

  return null
}

For Angular, call createBanner from a component's afterNextRender callback; the SSR guide shows it.