Connection hooks

These hooks read the client's two connection stores: the WebSocket's health and the device's network. The two can disagree: a socket can drop on a working network, and a device can lose its network while the socket still looks healthy. Connection explains both stores, and Connection status shows them in the UI.

Each entry gives the signature, then:

• Returns: what the hook gives back.
• Reads: the store or the context it reads.
• Re-renders: what makes the component render again.
• Needs: where the component must sit, and what the hook does outside that place.

useWSConnectionState

Returns the health of the client's WebSocket.

useWSConnectionState(): WSConnectionState | undefined

• Returns: { isHealthy, lastHealthyAt, lastUnhealthyAt }. isHealthy is always a boolean, so !isHealthy is safe.
• Reads: client.wsConnection.state, all of it.
• Re-renders: on every change to the store: each drop, each reconnect, and a deliberate client.closeConnection().
• Needs: Chat. Throws outside it.

The store records a drop the moment it happens, and most drops recover in under a second. Before you show "Reconnecting…", wait client.wsConnection.config.offlineNotificationDisplayDelayMs, 5 seconds by default, and cancel the wait if the socket comes back. Socket health shows how, and Chat's own banner, below, does it already.

useNetworkConnectionState

Returns the device's network status.

useNetworkConnectionState(): NetworkConnectionState | undefined

• Returns: { isOnline, lastOnlineAt, lastOfflineAt }. isOnline is undefined while the status is unknown, so test isOnline === false. !isOnline is also true while the status is unknown.
• Reads: client.networkConnection.state, all of it.
• Re-renders: on every change to the store.
• Needs: Chat. Throws outside it.

Who reports the network status, in a browser and elsewhere, is on Device network.

useNetworkConnectionStateSelector

Returns a selection of the device's network status.

useNetworkConnectionStateSelector<O extends Readonly<Record<string, unknown> | Readonly<unknown[]>>>(selector: (state: NetworkConnectionState) => O): O | undefined

• Returns: what the selector returns, an object or a tuple.
• Reads: client.networkConnection.state, through your selector.
• Re-renders: when a value in the selection changes. Define the selector at module scope: a new selector function on each render makes the hook subscribe again, as Selector identity explains.
• Needs: Chat. Throws outside it.

Use it instead of useNetworkConnectionState when the component needs only part of the status:

import type { NetworkConnectionState } from "stream-chat";
import { useNetworkConnectionStateSelector } from "stream-chat-react";

const isOnlineSelector = (state: NetworkConnectionState) => ({
  isOnline: state.isOnline,
});

export const OfflineBadge = () => {
  const { isOnline } =
    useNetworkConnectionStateSelector(isOnlineSelector) ?? {};

  if (isOnline !== false) return null;
  return <span className="offline-badge">Offline</span>;
};

The WebSocket store has no selector hook. Select from it with useStateStore(client.wsConnection.state, selector).

useReportLostConnectionSystemNotification

Shows a system notification while the client can't reach Stream, and removes it when it can again.

useReportLostConnectionSystemNotification(): void

It reads both stores and picks the message:

• when the device reports no network: "Waiting for network…";
• when the network is up or unknown and the socket is down: "Reconnecting…". After a drop, it waits offlineNotificationDisplayDelayMs first, and shows nothing if the socket comes back in that time. A socket that is already down when the hook mounts shows the message at once.

The notification has the type system:network:connection:lost for both messages, the severity loading, and no timeout. It's removed when the connection is back, and when the component unmounts.

• Returns: nothing.
• Reads: client.networkConnection.state and client.wsConnection.state, through its own subscriptions, so the component calling it doesn't re-render when they change.
• Re-renders: never by itself.
• Needs: Chat. Throws outside it.

Chat calls this hook already. Calling it again adds a second notification. To change how the banner looks, filter system notifications by its type: see Notification hooks and the System notification banner recipe. To change the wait, set offlineNotificationDisplayDelayMs:

client.config.set({
  client: { wsConnection: { offlineNotificationDisplayDelayMs: 2_000 } },
});