# Connection hooks

> **Info:** This is release candidate documentation for **Stream Chat React SDK v15**. For the latest stable version, see the [latest version (v14)](https://getstream.io/chat/docs/sdk/react/).

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](https://getstream.io/chat/docs/sdk/react/v15/state/connection/) explains both stores, and [Connection status](https://getstream.io/chat/docs/sdk/react/v15/features/app-experience/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.

```ts
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](https://getstream.io/chat/docs/sdk/react/v15/state/connection/#socket-health) shows how, and `Chat`'s own banner, below, does it already.

## useNetworkConnectionState

Returns the device's network status.

```ts
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](https://getstream.io/chat/docs/sdk/react/v15/state/connection/#device-network).

## useNetworkConnectionStateSelector

Returns a selection of the device's network status.

```ts
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](https://getstream.io/chat/docs/sdk/react/v15/ui/reading-state-in-components/#selector-identity) explains.
- **Needs:** `Chat`. Throws outside it.

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

```tsx
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.

```ts
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](https://getstream.io/chat/docs/sdk/react/v15/reference/hooks/notification-hooks/) and the [System notification banner](https://getstream.io/chat/docs/sdk/react/v15/recipes/app/system-notification-banner/) recipe. To change the wait, set `offlineNotificationDisplayDelayMs`:

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

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/v15/reference/hooks/connection-hooks/](https://getstream.io/chat/docs/sdk/react/v15/reference/hooks/connection-hooks/).