WsStatus

Code

import { WsStatus, type WsState } from "@fadymondy/nasaq/web";declare function reconnect(): void;export function Header({ state, latency, retryAt }: { state: WsState; latency: number; retryAt: number }) {  return <WsStatus state={state} latencyMs={latency} retryAt={retryAt} attempt={2} onRetry={() => reconnect()} />;}

Loading & States · beta

Live examples and controls: WsStatus in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/ws-status.json

The state of a live connection (WebSocket or SSE): live with its latency, connecting, reconnecting with a countdown, or offline. Your socket code drives state, latencyMs and retryAt; the component only shows them.

When to useCopy Anchor Link

• The header of a dashboard with live data.
• A banner when the connection drops and data may be stale.

When not to useCopy Anchor Link

• Plain internet connectivity for the whole app: use a page-level offline banner.

ImportCopy Anchor Link

import { WsStatus } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { WsStatus, type WsState } from "@fadymondy/nasaq/web";

declare function reconnect(): void;

export function Header({ state, latency, retryAt }: { state: WsState; latency: number; retryAt: number }) {
  return <WsStatus state={state} latencyMs={latency} retryAt={retryAt} attempt={2} onRetry={() => reconnect()} />;
}

AnatomyCopy Anchor Link

WsStatus                        data-slot="ws-status" data-state data-variant
├─ dot                          pulses while connected
├─ label                        role="status": Live, Connecting, Reconnecting, Offline
├─ countdown                    "Retrying in 0:12" (outside the live region)
├─ latency                      signal bars and "42 ms"
└─ Retry now                    when reconnecting or offline and onRetry is set

APICopy Anchor Link

WsStatus: every div prop except children, plus:

Helpers (pure, tested): latencyQuality, formatLatency, backoffDelay(attempt), formatCountdown, signalBars. useCountdown(at) is the hook behind the countdown.

ExamplesCopy Anchor Link

Banner

import { WsStatus } from "@fadymondy/nasaq/web";

export const Offline = () => <WsStatus variant="banner" state="offline" lastConnectedAt={Date.now() - 120_000} onRetry={() => {}} />;

AccessibilityCopy Anchor Link

• The state label is role="status", so a change is announced politely. The ticking countdown is outside it, so it is not read every second.
• State is a word and an icon as well as colour. The signal bars are decorative; the number and the title carry the meaning.
• Motion (pulse, spin) respects reduced motion.

RTL & i18nCopy Anchor Link

• English and Arabic strings follow the Nasaq locale. Latency ("42 ms") and the countdown are dir="ltr".

Styling & tokensCopy Anchor Link

• Uses --nq-success, --nq-info, --nq-warning, --nq-danger and their soft and text tokens.
• Target [data-slot="ws-status"][data-state="offline"].

Do / Don'tCopy Anchor Link

• Do back off between attempts and pass the real retryAt.
• Do tell people when data may be stale.
• Don't show latency while not connected.
• Don't flip states faster than about once a second; debounce in your socket code.

RelatedCopy Anchor Link

• Status
• Alert
• RealtimeCounter

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-loading-states-ws-status--docs