# use-websocket

> Base abstraction for using WebSockets in React

Latest version **0.2.0** (published 2024-01-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install use-websocket
pnpm add use-websocket
yarn add use-websocket
bun add use-websocket
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2024-01-14 |
| First published | 2018-10-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 17.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Aaron Casanova |
| Maintainers | aaronccasanova |

## Links

- npm: https://www.npmjs.com/package/use-websocket
- Repository: https://github.com/aaronccasanova/aacc
- Homepage: https://github.com/aaronccasanova/aacc/blob/main/hooks/use-websocket/README.md
- Issues: https://github.com/aaronccasanova/aacc/issues
- npm.io page: https://npm.io/package/use-websocket

## Recent versions

- 0.2.0 (latest) — 2024-01-14
- 0.1.2 — 2022-12-31
- 0.0.0 — 2022-12-30
- 0.1.1 — 2018-11-02
- 0.1.0 — 2018-10-30

## README

# (WIP) use-websocket

Base abstraction for using WebSockets in React.

> Status: (WIP) The API is unstable and may change in the future.

## Goals

- Simplify WebSocket usage in React.
- Keep API surface small.
- Avoid opinionated abstractions.
- Encourage community abstractions.
- See [motivation](#motivation) for more details.

## Installation

```sh
npm install use-websocket
```

## Usage

### Basic (Connect on mount)

```jsx
function App() {
  const [data, setData] = React.useState([])

  const { webSocket, status } = useWebSocket(url, {
    onMessage: (e) => setData((data) => [...data, e.data]),
  })

  if (status !== 'open') return <div>Connecting...</div>

  return (
    <div>
      <button onClick={() => webSocket.send('hi')}>Greet</button>
      <ul>
        {data.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
    </div>
  )
}
```

### Manual (Connect on event)

```jsx
function App() {
  const [data, setData] = React.useState([])

  const connectOnMount = false

  const { webSocket, status, connect } = useWebSocket(url, {
    connectOnMount,
    onMessage: (e) => setData((data) => [...data, e.data]),
  })

  return (
    <div>
      {status === 'closed' && (
        <button onClick={() => connect()}>Connect</button>
      )}
      <button onClick={() => webSocket.send('hi')}>Greet</button>
      <ul>
        {data.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
    </div>
  )
}
```

## Motivations

The `use-websocket` package was created to reduce boilerplate when using
WebSockets in React applications and provide a minimal API over the WebSocket
standard. Our goal is to simplify the integration of WebSocket functionality
into React apps and avoiding opinionated abstractions. The simplicity hopes to
make it easier for developers to use the WebSocket API and for the community to
create additional abstractions. We encourage the development of community
packages built on top of "use-websocket" and welcome contributions and feedback
from the community.

---
_Source: https://npm.io/package/use-websocket · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._