# use-subscription

> Reusable hooks

Latest version **1.13.0** (published 2026-09-09) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 73/100 (B)** — status: active.

Positive: has types package; no vulnerabilities; has provenance; recently updated; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.13.0 |
| Published | 2026-09-09 |
| First published | 2019-03-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/use-subscription) |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 6.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 250060 |
| Maintainers | fb, react-bot |

## Links

- npm: https://www.npmjs.com/package/use-subscription
- Repository: https://github.com/react/react
- Homepage: https://github.com/react/react#readme
- Issues: https://github.com/react/react/issues
- npm.io page: https://npm.io/package/use-subscription

## Dependencies (1)

- [use-sync-external-store](https://npm.io/package/use-sync-external-store.md) ^1.7.0

## Recent versions

- 1.13.0 (latest) — 2026-09-09
- 1.13.0-canary-2b19aecd-20260916 (canary) — 2026-09-16
- 0.0.0-experimental-ff8f88fc-20260915 (experimental) — 2026-09-15
- 1.13.0-canary-d5736f09-20260507 (next) — 2026-05-08
- 1.10.0-rc.1 (rc) — 2024-11-14
- 1.10.0-beta-26f2496093-20240514 (beta) — 2024-05-14
- 1.13.0-canary-ff8f88fc-20260915 — 2026-09-15
- 0.0.0-experimental-9b938532-20260914 — 2026-09-14
- 1.13.0-canary-9b938532-20260914 — 2026-09-14
- 1.13.0-canary-019019be-20260911 — 2026-09-11
- 0.0.0-experimental-019019be-20260911 — 2026-09-11
- 0.0.0-experimental-82c44beb-20260910 — 2026-09-10
- 1.13.0-canary-82c44beb-20260910 — 2026-09-10
- 0.0.0-experimental-1d34f91d-20260909 — 2026-09-09
- 1.13.0-canary-1d34f91d-20260909 — 2026-09-09
- … 2691 more at https://npm.io/package/use-subscription/versions

## README

# use-subscription

React Hook for subscribing to external data sources.

**You may now migrate to [`use-sync-external-store`](https://www.npmjs.com/package/use-sync-external-store) directly instead, which has the same API as [`React.useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore). The `use-subscription` package is now a thin wrapper over `use-sync-external-store` and will not be updated further.**

# Installation

```sh
# Yarn
yarn add use-subscription

# NPM
npm install use-subscription
```

# Usage

To configure a subscription, you must provide two methods: `getCurrentValue` and `subscribe`.

In order to avoid removing and re-adding subscriptions each time this hook is called, the parameters passed to this hook should be memoized. This can be done by wrapping the entire subscription with `useMemo()`, or by wrapping the individual callbacks with `useCallback()`.

## Subscribing to event dispatchers

Below is an example showing how `use-subscription` can be used to subscribe to event dispatchers such as DOM elements.

```js
import React, { useMemo } from "react";
import { useSubscription } from "use-subscription";

// In this example, "input" is an event dispatcher (e.g. an HTMLInputElement)
// but it could be anything that emits an event and has a readable current value.
function Example({ input }) {

  // Memoize to avoid removing and re-adding subscriptions each time this hook is called.
  const subscription = useMemo(
    () => ({
      getCurrentValue: () => input.value,
      subscribe: callback => {
        input.addEventListener("change", callback);
        return () => input.removeEventListener("change", callback);
      }
    }),

    // Re-subscribe any time our input changes
    // (e.g. we get a new HTMLInputElement prop to subscribe to)
    [input]
  );

  // The value returned by this hook reflects the input's current value.
  // Our component will automatically be re-rendered when that value changes.
  const value = useSubscription(subscription);

  // Your rendered output goes here ...
}
```

## Subscribing to observables

Below are examples showing how `use-subscription` can be used to subscribe to certain types of observables (e.g. RxJS `BehaviorSubject` and `ReplaySubject`).

**Note** that it is not possible to support all observable types (e.g. RxJS `Subject` or `Observable`) because some provide no way to read the "current" value after it has been emitted.

### `BehaviorSubject`
```js
const subscription = useMemo(
  () => ({
    getCurrentValue: () => behaviorSubject.getValue(),
    subscribe: callback => {
      const subscription = behaviorSubject.subscribe(callback);
      return () => subscription.unsubscribe();
    }
  }),

  // Re-subscribe any time the behaviorSubject changes
  [behaviorSubject]
);

const value = useSubscription(subscription);
```

### `ReplaySubject`
```js
const subscription = useMemo(
  () => ({
    getCurrentValue: () => {
      let currentValue;
      // ReplaySubject does not have a sync data getter,
      // So we need to temporarily subscribe to retrieve the most recent value.
      replaySubject
        .subscribe(value => {
          currentValue = value;
        })
        .unsubscribe();
      return currentValue;
    },
    subscribe: callback => {
      const subscription = replaySubject.subscribe(callback);
      return () => subscription.unsubscribe();
    }
  }),

  // Re-subscribe any time the replaySubject changes
  [replaySubject]
);

const value = useSubscription(subscription);
```

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