Add this component

npx zentauri-ui add network-status

Accessibility notes

Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.

Dependency notes

Check Installation for shared peers. This component keeps styling in Tailwind classes and the --zui-* token contract.

Feedback

Network Status for connectivity feedback

Use the network status component to surface live connectivity in the browser. Built on navigator.onLine and the Network Information API, it tracks online/offline transitions and connection quality, auto-coloring a status dot (green online, red offline, amber for a slow connection) with an optional pulsing ring and detail readout.

OnlineSlow connectionOffline

Network status variants playground

Pick a connectivity state, appearance, and size to preview the network status indicator live. Toggle Show output / Show code and the snippet updates to match the selected variant. Leave the state on auto to track your real connection via navigator.onLine.

State

Appearance

Size

Animation

Show connection detail

Offline

All appearances

Every shipped appearance token at a glance. Click any swatch to load it into the playground above.

online

offline

slow

default

subtle

muted

primary

blue

cyan

green

lime

emerald

indigo

purple

pink

rose

sky

teal

yellow

orange

red

slate

gray

zinc

gradient-blue

gradient-green

gradient-purple

Network Status API

Generated from the package prop types and variant definitions.

NetworkStatus

NetworkStatusProps

Variants

Prop	Type	Default
size	`lgmdsm`	md

Behavior

Prop	Type	Default
appearance	`'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'red' \| 'slate' \| 'zinc' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-purple' \| 'slow' \| 'gray' \| 'subtle' \| 'muted' \| 'primary' \| 'online' \| 'offline' \| null \| undefined`	none
labelsOverride the default status copy.	`NetworkStatusLabels \| undefined`	none
onlineControlled connectivity. When provided, live `navigator.onLine` detection is disabled and this value drives the status — useful for SSR, demos, and tests.	`boolean \| undefined`	none
onStatusChangeCalled whenever the connectivity snapshot changes.	`((info: NetworkStatusInfo) => void) \| undefined`	none
pulseRender a pulsing ring behind the dot while online.	`boolean \| undefined`	none
renderFully replace the rendered content with a custom node.	`((info: NetworkStatusInfo) => ReactNode) \| undefined`	none
showDetailShow the connection-quality detail (effective type / downlink).	`boolean \| undefined`	none
showLabelShow the text label next to the dot.	`boolean \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLSpanElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

NetworkStatusVariant

NetworkStatusVariantProps

Behavior

Prop	Type	Default
appearance	`'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'red' \| 'slate' \| 'zinc' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-purple' \| 'slow' \| 'gray' \| 'subtle' \| 'muted' \| 'primary' \| 'online' \| 'offline' \| null \| undefined`	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

NetworkStatusAnimated

NetworkStatusAnimatedProps

animated

Behavior

Prop	Type	Default
animation	`NetworkStatusAnimation \| undefined`	none
appearance	`'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'red' \| 'slate' \| 'zinc' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-purple' \| 'slow' \| 'gray' \| 'subtle' \| 'muted' \| 'primary' \| 'online' \| 'offline' \| null \| undefined`	none
labelsOverride the default status copy.	`NetworkStatusLabels \| undefined`	none
onlineControlled connectivity. When provided, live `navigator.onLine` detection is disabled and this value drives the status — useful for SSR, demos, and tests.	`boolean \| undefined`	none
onStatusChangeCalled whenever the connectivity snapshot changes.	`((info: NetworkStatusInfo) => void) \| undefined`	none
pulseRender a pulsing ring behind the dot while online.	`boolean \| undefined`	none
refAllows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).	`Ref<HTMLSpanElement> \| undefined`	none
renderFully replace the rendered content with a custom node.	`((info: NetworkStatusInfo) => ReactNode) \| undefined`	none
showDetailShow the connection-quality detail (effective type / downlink).	`boolean \| undefined`	none
showLabelShow the text label next to the dot.	`boolean \| undefined`	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLSpanElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

CSS variable overrides

Network Status CSS variables

Override these network status variables on :root, a theme selector, or a component wrapper.

52 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-network-status-online-dot-bg: #16a34a;
  --zui-network-status-offline-dot-bg: #dc2626;
  --zui-network-status-slow-dot-bg: #d97706;
  --zui-network-status-default-dot-bg: oklch(20.8% 0.042 265.755);
  --zui-network-status-subtle-dot-bg: oklch(92.9% 0.013 255.508);
  --zui-network-status-muted-dot-bg: oklch(44.6% 0.043 257.281);
  --zui-network-status-primary-dot-bg: oklch(20.8% 0.042 265.755);
  --zui-network-status-blue-dot-bg: #2563eb;
  --zui-network-status-cyan-dot-bg: #0891b2;
  --zui-network-status-green-dot-bg: #16a34a;
  --zui-network-status-lime-dot-bg: #65a30d;
  --zui-network-status-emerald-dot-bg: oklch(69.6% 0.17 162.48);
  --zui-network-status-indigo-dot-bg: oklch(39.8% 0.195 277.366);
  --zui-network-status-purple-dot-bg: oklch(43.8% 0.218 303.724);
  --zui-network-status-pink-dot-bg: oklch(45.9% 0.187 3.815);
  --zui-network-status-rose-dot-bg: oklch(64.5% 0.246 16.439);
  --zui-network-status-sky-dot-bg: oklch(68.5% 0.169 237.323);
  --zui-network-status-teal-dot-bg: oklch(70.4% 0.14 182.503);
  --zui-network-status-yellow-dot-bg: oklch(79.5% 0.184 86.047);
  --zui-network-status-orange-dot-bg: oklch(70.5% 0.213 47.604);
  --zui-network-status-red-dot-bg: #dc2626;
  --zui-network-status-slate-dot-bg: #475569;
  --zui-network-status-gray-dot-bg: oklch(55.1% 0.027 264.364);
  --zui-network-status-zinc-dot-bg: #52525b;
  --zui-network-status-label-fg: oklch(20.8% 0.042 265.755);
  --zui-network-status-detail-fg: oklch(44.6% 0.043 257.281);
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-network-status-online-dot-bg-dark: #22c55e;
  --zui-network-status-offline-dot-bg-dark: #ef4444;
}

What it does

NetworkStatus renders a colored status dot with an optional pulsing ring and text label that reflect the browser's live connectivity. It subscribes to the window online and offline events via the shared useNetworkStatus hook and reads connection-quality metrics (effectiveType, downlink, rtt) from the Network Information API, bucketing them into fast, moderate, slow, or unknown. The dot and ring color derive from the live status by default, shifting automatically between online (green), slow (amber), and offline (red). Every value is also available through the onStatusChange callback and the render prop for fully custom UI.

Composition and API

The Network Status component subscribes to the window online and offline events and to the Network Information API change event, re-rendering whenever connectivity changes. It exposes an onStatusChange callback with a full snapshot (online, status, quality, effectiveType, downlink, rtt, saveData), a render prop for fully custom output, and a controlled online prop for SSR, demos, and tests. Color is derived from the live status by default but can be overridden with any appearance token.

Common use cases

Show a persistent online/offline badge in an app header or status bar so users always know their connectivity at a glance. Warn users on a slow connection (3G or below) before they start a large upload or download. Disable or queue network-dependent actions while the user is offline and resume them automatically when connectivity is restored. Surface effective connection type and downlink speed in diagnostics dashboards or developer tooling to help debug performance issues in low-bandwidth environments.

Accessibility

The root carries data-status and data-quality attributes for styling and assistive context, and a text label communicates the state to screen readers. The pulsing ring is purely decorative (aria-hidden) and respects prefers-reduced-motion. Avoid relying on color alone — keep the label visible so the state is conveyed without depending on the dot color.

Next.js integration notes

navigator.onLine and the Network Information API are browser-only. The component is SSR-safe: it renders optimistically as online on the server and during the first client render, then syncs to the real connection inside an effect to avoid hydration mismatches. The Network Information API (effectiveType, downlink) is Chromium-only, so connection-quality detail degrades gracefully where it is unavailable.

FAQ

Which browsers support connection-quality detection?

Online/offline detection via navigator.onLine works everywhere. The richer connection quality (effectiveType, downlink, rtt) comes from the Network Information API, which is currently Chromium-only. When it is unavailable the component still reports online/offline and simply omits the quality detail.

How do I render a fixed state for SSR or testing?

Pass the controlled online prop (online or online={false}). When set, live detection is disabled and the component renders that state deterministically, which is ideal for server rendering, Storybook, and unit tests.

Can I customize the colors and labels?

Yes. Override the label copy with the labels prop ({ online, offline, slow }), force any palette with the appearance prop, and theme the dot via the --zui-network-status-* CSS variables. By default the appearance is derived from the live status.