---
title: Introduction
url: https://react-rx.dev/
---

[![react-rx-some-smaller](https://user-images.githubusercontent.com/81981/194187624-9abd09da-bf03-4886-b512-78c1f22fc2de.png)](https://react-rx.dev/)

> Hooks for combining React with RxJS Observables

Features:

- Works well with `Observables` emitting values synchronously. You don't pay the re-render-on-mount tax.
- Non-blocking by default — `useObservable` defers store updates; reach for `useSyncObservable` for controlled inputs.
- Lightweight. Implemented on top of a small React Hook based core.
- Full TypeScript support.

---
title: Guide
url: https://react-rx.dev/guide
---

# Getting Started

## Installation

```sh npm2yarn
npm i react-rx rxjs
```

## Observable Hooks

### Which one should I use?

- **Default to `useObservable`** — store updates are deferred, so previews, validation, lists, and other chrome stay responsive and play nicely with Suspense.
- **Reach for `useSyncObservable`** only when the value feeds a controlled input (caret/IME breakage or lost keystrokes under load) or must be read back synchronously in the same event. It is also the hook with the strict v4 SSR contract (server renders the `initialValue`, throws without one).

See [Suspense & deferred values](/examples/suspense) for a side-by-side demo, and the [v4 → v5 migration guide](/migrate/v4-to-v5) if you are upgrading.

### useObservable()

Use observables in React components with the `useObservable` hook.

If you need to subscribe to an observable in your component, this hook will give you the current value from it. Later emissions update the component at deferred priority — urgent renders keep the previous value until a background render catches up.

Example:

```tsx
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {interval} from 'rxjs'

function MyComponent(props) {
  const observable = useMemo(() => interval(100), [])
  const number = useObservable(observable, 0)

  return <>The number is {number}</>
}
```

The `initialValue` argument is optional. If it is omitted, the value returned from `useObservable` may be `undefined` initially. If the observable emits a value _synchronously_ at subscription time, that value will be used as the initial value, and any `initialValue` passed as argument to `useObservable` will be ignored on the first render (mounts and `<Activity>` reveals are not deferred):

```tsx
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {of} from 'rxjs'

// This component will never render "Hello mars!" since the observable emits "world" synchronously.
function MyComponent(props) {
  const observable = useMemo(() => of('world'), [])
  const planet = useObservable(observable, 'mars')

  return <>Hello {planet}!</>
}
```

The difference between `useObservable` and `useSyncObservable` is how _updates_ propagate (deferred vs synchronous), not the first render. On the server, `useObservable` paints what the first client render will show (here `"world"`), while `useSyncObservable` would paint the `initialValue` (`"mars"`).

The `disabled` option pauses the hook's _active_ subscription — think of it like `pause: true`. While `disabled` is `true`, the hook will not keep a live subscription that pushes updates into the component, and it returns the last value it already received (or the `initialValue` if nothing has been received yet). Turning `disabled` back to `false` resumes the live subscription.

Important: `disabled` does **not** skip the hook's initial warm-up subscription. Both hooks always briefly subscribe during render so a synchronous emission can become the current snapshot. That means cold observables with subscribe-time side effects (for example `fromFetch`) still run that work even when `disabled` is `true`.

```tsx
import {useEffect, useState} from 'react'
import {useObservable} from 'react-rx'
import {Subject} from 'rxjs'

// While `disabled` is true, later async emissions are ignored and the last
// received value (here the initialValue "mars") is returned.
function MyComponent(props) {
  const [observable] = useState(() => new Subject<string>())
  const planet = useObservable(observable, 'mars', {disabled: true})

  useEffect(() => {
    observable.next('world')
  }, [observable])

  return <>Hello {planet}!</>
}
```

If the goal is to avoid _any_ subscription to a particular observable, do not use `disabled`. Pass a different observable instead — for example swap in `of(null)` until you are ready to fetch:

```tsx
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {of} from 'rxjs'
import {fromFetch} from 'rxjs/fetch'

function Users({shouldFetch}: {shouldFetch: boolean}) {
  // Prefer swapping the observable over `{disabled: !shouldFetch}`:
  // `disabled` still performs the render-phase warm-up subscribe, which would
  // fire the request even when `shouldFetch` is false.
  const users$ = useMemo(
    () =>
      shouldFetch
        ? fromFetch('https://api.github.com/users?per_page=5', {
            selector: (response) => response.json(),
          })
        : of(null),
    [shouldFetch],
  )
  const users = useObservable(users$, null)

  return <pre>{JSON.stringify(users, null, 2)}</pre>
}
```

Because the fetch observable is only created (and therefore only ever subscribed) when `shouldFetch` is true, this guarantees zero subscriptions to `fromFetch` until then.

### useSyncObservable()

Same signature as `useObservable`, but updates are synchronous (the previous default). Use it for controlled inputs:

```tsx
import type {ChangeEvent} from 'react'
import {useObservableEvent, useSyncObservable} from 'react-rx'
import {map, Subject, tap, type Observable} from 'rxjs'

const text$ = new Subject<string>()

function SearchField() {
  const handleChange = useObservableEvent((events$: Observable<ChangeEvent<HTMLInputElement>>) =>
    events$.pipe(
      map((e) => e.currentTarget.value),
      tap((value) => text$.next(value)),
    ),
  )
  const text = useSyncObservable(text$, '')

  return <input value={text} onChange={handleChange} />
}
```

### useObservablePromise()

Use this when you want **Suspense-powered data fetching** instead of tracking loading state in the stream.

`useObservable` is built on `useSyncExternalStore`. That is great for live values, but it cannot activate a [`Suspense`](https://react.dev/reference/react/Suspense#what-activates-a-suspense-boundary) boundary, and React 19.2 [`Activity`](https://react.dev/reference/react/Activity#pre-rendering-content-thats-likely-to-become-visible) pre-rendering only fetches data read with `use(promise)`.

`useObservablePromise` returns an instrumented Promise you pass to React's `use()`. The hook itself does **not** suspend — the consumer decides where the Suspense boundary lives:

```tsx
import {Suspense, use, useMemo} from 'react'
import {useObservablePromise} from 'react-rx'
import {fromFetch} from 'rxjs/fetch'

function Users() {
  const users$ = useMemo(
    () =>
      fromFetch('https://api.github.com/users?per_page=5', {
        selector: (response) => response.json(),
      }),
    [],
  )
  const promise = useObservablePromise(users$)

  return (
    <Suspense fallback={<p>Loading users…</p>}>
      <UsersList promise={promise} />
    </Suspense>
  )
}

function UsersList({promise}: {promise: Promise<unknown>}) {
  const users = use(promise)
  return <pre>{JSON.stringify(users, null, 2)}</pre>
}
```

Prefer creating the promise in a parent that does **not** suspend (as above), so Suspense retries always see the same promise identity. The single-component form also works when the observable identity is stable across retries (module-level cache, or a shared `WeakMap` keyed by request):

```tsx
function UsersList({users$}) {
  // `users$` must be referentially stable for the in-flight request
  const users = use(useObservablePromise(users$))
  return <pre>{JSON.stringify(users, null, 2)}</pre>
}
```

**Semantics**

- Suspends until the observable's **first** emission (`firstValueFrom` semantics).
- Later emissions update the UI **without** re-showing the Suspense fallback.
- Sync sources (`of`, `BehaviorSubject`, replayed `shareReplay`) never flash a fallback.
- Errors reject the promise and surface through the nearest Error Boundary. Prefer `catchError` on the _inner_ observable when you want graceful degradation instead of a boundary.
- Completing without emitting rejects with RxJS `EmptyError`.
- Swapping to a **different** observable returns a new pending promise, so the fallback shows again. To keep the previous content visible instead, change the observable inside [`startTransition`](https://react.dev/reference/react/startTransition) or read the promise through [`useDeferredValue`](https://react.dev/reference/react/useDeferredValue) — both also give you a staleness signal (`isPending`, or `deferredPromise !== promise`) to dim stale content while the new data loads.

**Not for `startWith` placeholders.** Because the first emission unblocks Suspense, `startWith('loading')` fulfills immediately with `"loading"`. For placeholder / loading-value patterns, use `useObservable` instead.

**Options**

```ts
useObservablePromise(observable$, {
  disabled?: boolean // default false — when true, this component starts no fetch
  ttl?: number // default 500 — retention (ms) after settle with no subscribers
})
```

Unlike `useObservable`'s `disabled` (which still runs a warm-up probe), `disabled: true` here fully prevents fetching on behalf of this component. The returned promise is still the shared cache entry — a sibling or `preloadObservablePromise` can warm it.

`ttl` controls how long a settled value stays reusable after unmount. Remount within the window reuses the promise (no refetch, no fallback). After it expires, the next mount refetches. Eviction only affects future consumers: components that are still mounted keep their value — hiding an `<Activity>` tree longer than `ttl` never drops what it already rendered.

**Deferring expensive re-renders**

Like every external-store subscription, emission-driven updates render at synchronous priority — React cannot time-slice them directly. If an emission re-renders something expensive, defer the promise itself and memoize the expensive subtree. The synchronous pass then skips the memoized subtree (it still sees the old promise), and its re-render happens at deferred priority: time-sliced, interruptible by urgent updates, and coalesced under rapid emissions.

```tsx
const BigChart = memo(function BigChart({promise}) {
  const data = use(promise)
  return <Chart data={data} />
})

function Dashboard({metrics$}) {
  const promise = useObservablePromise(metrics$)
  const deferredPromise = useDeferredValue(promise)
  return <BigChart promise={deferredPromise} />
}
```

The `memo` is load-bearing: without it the subtree re-renders during the synchronous pass anyway (with the old promise), defeating the deferral — see [deferring re-rendering for a part of the UI](https://react.dev/reference/react/useDeferredValue#deferring-re-rendering-for-a-part-of-the-ui). Swapped promises are always pre-settled, so the deferred subtree never suspends — it just lags by a paint under load. When the stream itself is too chatty, throttling in the pipe (`auditTime`, `throttleTime`) remains the RxJS-native complement.

**Preloading**

Warm the cache outside of render (hover, route loaders) with `preloadObservablePromise`. Calling it starts the source subscription immediately. Pending entries are never timed out — if the observable never emits or completes, the promise stays pending and the subscription stays alive until it settles (or the process tears down). Bound hang risk with RxJS [`timeout`](https://rxjs.dev/api/operators/timeout) (or cancel the source) when the preload can stall:

```tsx
import {preloadObservablePromise, useObservablePromise} from 'react-rx'

function TabButton({users$, onSelect}) {
  return (
    <button
      type="button"
      onMouseEnter={() => preloadObservablePromise(users$, {ttl: 5_000})}
      onClick={onSelect}
    >
      Users
    </button>
  )
}
```

**Which hook when?**

| Need                                                   | Hook                   |
| ------------------------------------------------------ | ---------------------- |
| Live values, timers, subjects, optional `initialValue` | `useObservable`        |
| Controlled inputs / synchronous store updates          | `useSyncObservable`    |
| Async data + Suspense / Activity pre-render            | `useObservablePromise` |
| Event → observable pipelines                           | `useObservableEvent`   |

For cold observables you want to share across subscribers yourself, keep using RxJS `shareReplay({bufferSize: 1, refCount: true})` — the hook's `ttl` is a lightweight mount/unmount cache, not a full query cache.

### useObservableEvent()

This creates an event handler that can be used to create an observable from events.

Here's an example of a component that displays the current value from a range input:

```tsx
import {useState} from 'react'
import {useObservableEvent} from 'react-rx'
import {filter, map, tap} from 'rxjs'

const ShowSliderValue = () => {
  const [value, setValue] = useState(1)
  const handleChange = useObservableEvent((value$) =>
    value$.pipe(
      // Ignore nullish values
      filter(nonNullable),
      // Cast to number
      map((value) => Number(value)),
      // Update local state
      tap(setValue),
    ),
  )

  return (
    <>
      <input
        type="range"
        value={value}
        onChange={(event) => handleChange(event.target.value)}
        min={1}
        max={10}
      />
      <div>Value is: {value}</div>
    </>
  )
}

function nonNullable<T>(v: T): v is NonNullable<T> {
  return v != null
}
```

---
title: API
url: https://react-rx.dev/reference
---

# React hooks

## useObservable()

A React hook that returns the current/latest value from an observable. Store updates are **deferred by default** via [`useDeferredValue`](https://react.dev/reference/react/useDeferredValue): urgent renders keep the previous value while a background render catches up. That makes it safe to suspend on the returned value without replacing already-revealed UI with a Suspense fallback.

The deferral is **identity-coherent**: unlike a bare `useDeferredValue(useObservable(...))`, the observable identity and its value are deferred as one snapshot, and when the observable identity changes (e.g. it is memoized on a document id that just changed) the hook falls back to the live value — typically the new observable's synchronous emission or the `initialValue` — so the previous identity's value never renders under the new one.

Mounts, remounts, and `<Activity>` reveals still render the current snapshot synchronously (no initial-value flash). On the server, this hook renders exactly what the client's first paint will show (a synchronous emission when there is one, else the resolved `initialValue`, else nothing) and never throws for a missing `initialValue`.

Prefer this hook for previews, validation, lists, and other non-input reads. Use [`useSyncObservable`](#usesyncobservable) for controlled inputs or strict SSR control.

**Signature**

```ts
function useObservable<T>(observable$: Observable<T>): T | undefined
function useObservable<T>(
  observable$: Observable<T>,
  initialValue: T | (() => T),
  options?: UseObservableOptions,
): T

interface UseObservableOptions {
  disabled?: boolean
}
```

`disabled` pauses the live subscription (later emissions stop updating the component; the last value is kept). It does **not** skip the render-phase warm-up subscription — see the [guide](/guide) for swapping the observable when you need zero subscriptions.

**Example**

```tsx
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {interval} from 'rxjs'

function MyComponent() {
  const observable = useMemo(() => interval(100), [])
  const number = useObservable(observable, 0)

  return <>The number is {number}</>
}
```

## useSyncObservable()

A React hook that returns the current/latest value from an observable **synchronously** via [`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore). This is the v4 `useObservable` behavior.

Use it when the value feeds a controlled input (or must stay consistent within the same event), or when you need strict control over server markup: the server renders the resolved `initialValue` and throws without one.

**Caveat:** store mutations cannot be marked as Transitions. Suspending on a value returned by this hook replaces already-visible content with the nearest Suspense fallback — see the [useSyncExternalStore caveats](https://react.dev/reference/react/useSyncExternalStore#caveats). Compare the two hooks in the [Suspense example](/examples/suspense).

**Signature**

```ts
function useSyncObservable<T>(observable$: Observable<T>): T | undefined
function useSyncObservable<T>(
  observable$: Observable<T>,
  initialValue: T | (() => T),
  options?: UseObservableOptions,
): T
```

**Example**

```tsx
import type {ChangeEvent} from 'react'
import {useObservableEvent, useSyncObservable} from 'react-rx'
import {map, Subject, tap, type Observable} from 'rxjs'

const text$ = new Subject<string>()

function SearchField() {
  const handleChange = useObservableEvent((events$: Observable<ChangeEvent<HTMLInputElement>>) =>
    events$.pipe(
      map((e) => e.currentTarget.value),
      tap((value) => text$.next(value)),
    ),
  )
  // Controlled input values must update synchronously.
  const text = useSyncObservable(text$, '')

  return <input value={text} onChange={handleChange} />
}
```

## useObservablePromise()

A React hook that turns an observable into a `use()`-compatible promise for Suspense and Activity pre-rendering.

**Signature**

```ts
function useObservablePromise<T>(
  observable: Observable<T>,
  options?: UseObservablePromiseOptions,
): ObservablePromise<T>

interface UseObservablePromiseOptions {
  disabled?: boolean
  ttl?: number
}

type ObservablePromise<T> = Promise<T> &
  ({status: 'pending'} | {status: 'fulfilled'; value: T} | {status: 'rejected'; reason: unknown})
```

The hook does **not** suspend. Pass the returned promise to React's [`use`](https://react.dev/reference/react/use) inside a `<Suspense>` boundary. Suspends until the first emission; later emissions update without re-suspending. Errors reject the promise (Error Boundary). See the [guide](/guide) for `startWith` caveats, `disabled` / `ttl`, and when to prefer `useObservable`.

**Example**

```tsx
import {Suspense, use, useMemo} from 'react'
import {useObservablePromise} from 'react-rx'
import {fromFetch} from 'rxjs/fetch'

function Profile({url}: {url: string}) {
  const data$ = useMemo(() => fromFetch(url, {selector: (r) => r.json()}), [url])
  const promise = useObservablePromise(data$)
  return (
    <Suspense fallback="Loading…">
      <Pre promise={promise} />
    </Suspense>
  )
}

function Pre({promise}: {promise: Promise<unknown>}) {
  return <pre>{JSON.stringify(use(promise), null, 2)}</pre>
}
```

## preloadObservablePromise()

Warm the `useObservablePromise` cache outside of rendering (for example on `mouseenter` or in a route loader). Not a hook — callable anywhere. Returns the same promise instance the hook would return for that observable.

Calling it starts the source subscription immediately. Pending entries are never timed out, so a never-emitting / hung observable keeps both the promise and the subscription alive until it settles. Prefer RxJS [`timeout`](https://rxjs.dev/api/operators/timeout) (or cancel the source) when a preload can stall.

**Signature**

```ts
function preloadObservablePromise<T>(
  observable: Observable<T>,
  options?: {ttl?: number},
): ObservablePromise<T>
```

Default `ttl` is `5000` (longer than the hook default) so a hover-warmed value survives until click/navigation.

## useObservableEvent()

A React hook that turns an event handler into an observable stream. Pass a function that receives an observable of events and returns an observable of side effects; the hook returns a stable callback you can attach to DOM or component event props.

When the returned callback is invoked, its single argument is emitted into the observable. The pipeline you return is subscribed for the lifetime of the component, and unsubscribed on unmount.

**Signature**

```ts
function useObservableEvent<T, U>(
  handleEvent: (arg: Observable<T>) => Observable<U>,
): (arg: T) => void
```

**Example**

```tsx
import {useState} from 'react'
import {useObservableEvent} from 'react-rx'
import {filter, map, tap} from 'rxjs'

const ShowSliderValue = () => {
  const [value, setValue] = useState(1)
  const handleChange = useObservableEvent((value$) =>
    value$.pipe(
      // Ignore nullish values
      filter(nonNullable),
      // Cast to number
      map((value) => Number(value)),
      // Update local state
      tap(setValue),
    ),
  )

  return (
    <>
      <input
        type="range"
        value={value}
        onChange={(event) => handleChange(event.target.value)}
        min={1}
        max={10}
      />
      <div>Value is: {value}</div>
    </>
  )
}

function nonNullable<T>(v: T): v is NonNullable<T> {
  return v != null
}
```

---
title: v4 to v5
url: https://react-rx.dev/migrate/v4-to-v5
---

# Migrating from v4 to v5

v5 is a major release. This page covers every breaking change and the recommended upgrade path for the headline hook change.

## Requirements

|               | v4                                            | v5                                     |
| ------------- | --------------------------------------------- | -------------------------------------- |
| React         | 18+                                           | `^19.2`                                |
| RxJS          | 7.x (operators often from `'rxjs/operators'`) | `^7.2`, import operators from `'rxjs'` |
| Node          | (unspecified)                                 | `>=22.12`                              |
| Module format | CJS + ESM                                     | ESM-only                               |

See the [RxJS import migration guide](https://rxjs.dev/guide/importing#how-to-migrate) if you still import from `'rxjs/operators'`.

## Deferred `useObservable` (headline change)

In v4, `useObservable` was built on [`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore) and forced **synchronous** React updates. Under load that blocks the main thread for chrome that does not need to be sync — validation, presence, previews, permissions, and similar.

v5 makes that the library default:

- **`useObservable`** — store updates are deferred with `useDeferredValue`. Urgent renders keep the previous value; a background render catches up. Mounts, remounts, and `<Activity>` reveals still show the live snapshot (no initial-value flash). The deferral is identity-coherent: when the observable identity changes, the hook falls back to the live value so the previous observable's value never renders under the new one — a stale-value bug a hand-rolled `useDeferredValue(useObservable(...))` wrapper is prone to.
- **`useSyncObservable`** — exact v4 synchronous behavior, including the strict server snapshot (`initialValue` on the server, throws without one).

### What you may notice

- **Controlled inputs** can lag or lose caret position under load if they keep using `useObservable` — switch those reads to `useSyncObservable`.
- The **rendered value can briefly trail the store**, so imperative reads or equality checks against it can observe a stale value. Keep a sync read for write-path equality when needed.
- **Render-count / test assertions** may see extra passes: one Object.is bail-out pass on mount when the snapshot is defined, and an urgent-plus-deferred pair per emission.
- **SSR** now renders synchronous emissions instead of the `initialValue`, and no longer throws when `initialValue` is omitted. Non-deterministic sync emissions can surface hydration mismatches that were previously masked. Synchronously erroring observables now fail the server render instead of exploding at hydration.

### Recommended: targeted migration

Keep calling `useObservable` everywhere. Switch only controlled-input (or same-event synchronous) reads to `useSyncObservable`:

```tsx
// Before (v4)
const text = useObservable(text$, '')
const items = useObservable(items$, [])

// After (v5) — only the input value needs to be sync
const text = useSyncObservable(text$, '')
const items = useObservable(items$, [])
```

Also remove redundant wrappers that are now built in:

```tsx
// Before
const results = useDeferredValue(useObservable(results$))

// After
const results = useObservable(results$)
```

### Fallback: mechanical rename

If you need a zero-behavior-change upgrade day, rename every `useObservable` → `useSyncObservable`, then adopt deferral incrementally by switching non-input reads back to `useObservable`.

### See it in action

The [Suspense & deferred values](/examples/suspense) example puts both hooks side by side on a search UI.

---
title: Simple
url: https://react-rx.dev/examples/simple
---

## Hello World

```tsx filename="App.tsx"
import {useObservable} from 'react-rx'
import {of} from 'rxjs'

const observable = of('World')

export default function App() {
  const data = useObservable(observable)

  return <h1>Hello, {data}!</h1>
}
```

## Counter

```tsx filename="App.tsx"
import {useObservable} from 'react-rx'
import {timer} from 'rxjs'

const observable = timer(0, 1000)

export default function App() {
  const seconds = useObservable(observable)
  return <>Seconds: {seconds}</>
}
```

---
title: Advanced counters
url: https://react-rx.dev/examples/counters
---

## Configurable interval

```tsx filename="App.tsx"
import {useMemo, useState} from 'react'
import {useObservable} from 'react-rx'
import {map, startWith, timer} from 'rxjs'

export default function App() {
  const [delay, setDelay] = useState(500)
  const observable = useMemo(
    () =>
      timer(500, delay).pipe(
        map((n) => `Count: ${n}`),
        startWith('Starting counter…'),
      ),
    [delay],
  )

  const label = useObservable(observable)
  return (
    <>
      Counter interval (ms):{' '}
      <input
        type="range"
        min={0}
        max={1000}
        step={100}
        value={delay}
        onChange={(e) =>
          setDelay(Number(e.currentTarget.value))
        }
      />
      {delay}
      <div>{label}</div>
    </>
  )
}
```

## Delayed tick

```tsx filename="App.tsx"
import {useObservable} from 'react-rx'
import {timer} from 'rxjs'

import {Ticker} from './Ticker'
import {TickerWithSubTick} from './TickerWithSubTick'

const observable = timer(0, 1000)

export default function App() {
  const tick = useObservable(observable, 0)

  return (
    <>
      <div>Tick: {tick}</div>
      <Ticker observable={observable} />
      <TickerWithSubTick
        observable={observable}
      />
    </>
  )
}
```

```tsx filename="Ticker.tsx"
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {
  distinctUntilChanged,
  map,
  type Observable,
  startWith,
  switchMap,
  timer,
} from 'rxjs'

export function Ticker(props: {
  observable: Observable<number>
}) {
  const observable = useMemo(
    () =>
      props.observable.pipe(
        distinctUntilChanged(),
        switchMap((tick) =>
          timer(300).pipe(map(() => tick)),
        ),
        startWith(0),
      ),
    [props.observable],
  )
  const tick = useObservable(observable)

  return <p>Delayed tick: {tick}</p>
}
```

```tsx filename="TickerWithSubTick.tsx"
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {
  distinctUntilChanged,
  map,
  type Observable,
  sampleTime,
  switchMap,
  timer,
} from 'rxjs'

const initial = {tick: 0, subtick: 0} as const

export function TickerWithSubTick(props: {
  observable: Observable<number>
}) {
  const observable = useMemo(
    () =>
      props.observable.pipe(
        distinctUntilChanged(),
        switchMap((tick) =>
          timer(0, 10).pipe(
            map((subtick) => ({
              tick,
              subtick,
            })),
          ),
        ),
        sampleTime(20),
      ),
    [props.observable],
  )
  const {tick, subtick} = useObservable(
    observable,
    initial,
  )

  return (
    <div>
      {tick}:{subtick}
    </div>
  )
}
```

## Fizz Buzz

```tsx filename="App.tsx"
import {useObservable} from 'react-rx'
import {map, take, timer} from 'rxjs'

const observable = timer(0, 500).pipe(
  map((n) => n + 1),
  map((n) => {
    const divBy3 = n % 3 === 0
    const divBy5 = n % 5 === 0
    const divBy3And5 = divBy3 && divBy5
    return divBy3And5
      ? 'Fizz Buzz'
      : divBy3
        ? 'Fizz'
        : divBy5
          ? 'Buzz'
          : String(n)
  }),
  map((n, i) => (
    <h1>
      {i + 1}: {n}
    </h1>
  )),
  take(100),
)

export default function App() {
  return useObservable(observable)
}
```

---
title: Error handling
url: https://react-rx.dev/examples/errors
---

```tsx filename="App.tsx"
import {useErrorBoundary} from 'use-error-boundary'

import {Example} from './Example'

export default function App() {
  const {ErrorBoundary, didCatch, error, reset} =
    useErrorBoundary()

  if (didCatch) {
    return (
      <>
        <div
          style={{
            color: 'crimson',
          }}
        >
          Oh no! An error occurred:
          <br />
          {error.message}
        </div>
        <button onClick={reset}>Try again</button>
      </>
    )
  }

  return (
    <ErrorBoundary>
      <Example />
    </ErrorBoundary>
  )
}
```

```tsx filename="Example.tsx"
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {
  mergeMap,
  of,
  Subject,
  throwError,
} from 'rxjs'

import {Counter} from './Counter'

const subject = new Subject<{
  error: boolean
  message: string
}>()

export function Example() {
  const messages = useMemo(
    () =>
      subject
        .asObservable()
        .pipe(
          mergeMap((value) =>
            value.error
              ? throwError(
                  () => new Error(value.message),
                )
              : of(value.message),
          ),
        ),
    [],
  )
  const message = useObservable(
    messages,
    'You did not click the button for: ',
  )

  return (
    <>
      <div>
        {message}
        <Counter />
      </div>
      <button
        type="button"
        onClick={() =>
          subject.next({
            error: true,
            message:
              "You clicked the button, didn't you!?",
          })
        }
      >
        DO NOT CLICK THE BUTTON
      </button>
    </>
  )
}
```

```tsx filename="Counter.tsx"
import {useMemo} from 'react'
import {useObservable} from 'react-rx'
import {timer} from 'rxjs'

export function Counter() {
  const observable = useMemo(
    () => timer(0, 1000),
    [],
  )
  const count = useObservable(observable, 0)
  return <>{count}s</>
}
```

Extra npm dependencies used by this example: `use-error-boundary`.

---
title: Todo app
url: https://react-rx.dev/examples/todo-app
---

```tsx filename="App.tsx"
import {
  ChangeEvent,
  type SyntheticEvent,
  useMemo,
} from 'react'
import {
  useObservable,
  useObservableEvent,
  useSyncObservable,
} from 'react-rx'
import {
  filter,
  map,
  scan,
  startWith,
  Subject,
  tap,
  withLatestFrom,
} from 'rxjs'
import {styled} from 'styled-components'

interface TodoItem {
  id: number
  text: string
}

const text$ = new Subject<string>()
const submit$ = new Subject<
  SyntheticEvent<HTMLFormElement>
>()
const textToItem = (text: string) => ({
  text,
  id: Date.now(),
})

function TodoApp() {
  // Handle input changes
  const handleInput = useObservableEvent<
    ChangeEvent<HTMLInputElement>,
    any
  >((input$) =>
    input$.pipe(
      map(
        (e: ChangeEvent<HTMLInputElement>) =>
          e.currentTarget.value,
      ),
      tap((value) => text$.next(value)),
    ),
  )

  // Handle form submissions
  const handleSubmit = useObservableEvent<
    SyntheticEvent<HTMLFormElement>,
    any
  >((event$) =>
    event$.pipe(
      tap((e) => {
        e.preventDefault()
        submit$.next(e)
        text$.next('')
      }),
    ),
  )

  // Create items stream
  const items$ = useMemo(
    () =>
      submit$.pipe(
        withLatestFrom(text$),
        map(([, text]) => text),
        filter((text) => text.length > 0),
        map(textToItem),
        scan(
          (items: TodoItem[], item) =>
            items.concat(item),
          [] as TodoItem[],
        ),
        startWith([]),
      ),
    [],
  )

  // Controlled input value must update synchronously to avoid caret/IME issues.
  const text = useSyncObservable(text$, '')
  const items = useObservable(items$, [])

  return (
    <Wrapper>
      <h3>TODO</h3>
      <TodoList items={items} />
      <form onSubmit={handleSubmit}>
        <label htmlFor="new-todo">
          What needs to be done?
        </label>
        <input
          id="new-todo"
          onChange={handleInput}
          value={text}
        />
        <button>Add #{items.length + 1}</button>
      </form>
    </Wrapper>
  )
}

interface ListProps {
  items: TodoItem[]
}

function TodoList(props: ListProps) {
  return (
    <ul>
      {props.items.map((item) => (
        <li key={item.id}>{item.text}</li>
      ))}
    </ul>
  )
}

const Wrapper = styled.div`
  label {
    display: block;
    margin-top: 10px;
  }
  input {
    box-sizing: border-box;
    width: 100%;
    padding: 5px;
  }
`

export default function App() {
  return <TodoApp />
}
```

Extra npm dependencies used by this example: `styled-components`.

---
title: Animation
url: https://react-rx.dev/examples/animation
---

```tsx filename="App.tsx"
import bezier from 'bezier-easing'
import {useMemo} from 'react'
import {
  useObservable,
  useObservableEvent,
} from 'react-rx'
import {
  map,
  startWith,
  Subject,
  switchMap,
  tap,
  timer,
} from 'rxjs'
import {styled} from 'styled-components'

const BALL_SIZE = 30
const BOX_SIZE = 300
const MAX_TOP = BOX_SIZE - BALL_SIZE

// Create subject for easing changes
const easing$ = new Subject<EasingName>()

function easeCustom(n: number) {
  return n
}

type EasingName = keyof typeof EASINGS

function AnimationExample() {
  // Handle easing changes
  const handleEasingChange = useObservableEvent<
    EasingName,
    any
  >((change$) =>
    change$.pipe(
      tap((easing) => easing$.next(easing)),
    ),
  )

  // Create animation stream
  const animation$ = useMemo(
    () =>
      easing$.pipe(
        startWith('easeCustom' as EasingName),
        switchMap((easing: EasingName) =>
          timer(0, 16).pipe(
            map((n) => (n % MAX_TOP) * 2),
            map((n) =>
              n > MAX_TOP ? MAX_TOP * 2 - n : n,
            ),
            map(
              (linearTop) =>
                [
                  EASINGS[easing](
                    linearTop / MAX_TOP,
                  ) * MAX_TOP,
                  easing,
                ] as [number, EasingName],
            ),
          ),
        ),
      ),
    [],
  )

  const [top, currentEasing] = useObservable(
    animation$,
    [0, 'easeCustom' as EasingName],
  )

  return (
    <>
      <SelectWrapperLabel>
        Easing function:
      </SelectWrapperLabel>
      <SelectWrapper>
        {Object.keys(EASINGS).map(
          (easingName) => (
            <label
              key={easingName}
              className={
                easingName === currentEasing
                  ? 'selected'
                  : ''
              }
            >
              <input
                tabIndex={0}
                type="checkbox"
                checked={
                  easingName === currentEasing
                }
                key={easingName}
                onChange={() =>
                  handleEasingChange(
                    easingName as EasingName,
                  )
                }
              />
              {easingName.substring(4)}
            </label>
          ),
        )}
      </SelectWrapper>
      <BoxWrapper>
        <Box>
          <Ball style={{top}} />
        </Box>
      </BoxWrapper>
    </>
  )
}

// --- easing definitions and stylings
const EASINGS = {
  easeCustom: easeCustom,
  easeInSine: bezier(0.47, 0, 0.745, 0.715),
  easeOutSine: bezier(0.39, 0.575, 0.565, 1),
  easeInOutSine: bezier(0.445, 0.05, 0.55, 0.95),
  easeInQuad: bezier(0.55, 0.085, 0.68, 0.53),
  easeOutQuad: bezier(0.25, 0.46, 0.45, 0.94),
  easeInOutQuad: bezier(
    0.455,
    0.03,
    0.515,
    0.955,
  ),
  easeInCubic: bezier(0.55, 0.055, 0.675, 0.19),
  easeOutCubic: bezier(0.215, 0.61, 0.355, 1),
  easeInOutCubic: bezier(0.645, 0.045, 0.355, 1),
  easeInQuart: bezier(0.895, 0.03, 0.685, 0.22),
  easeOutQuart: bezier(0.165, 0.84, 0.44, 1),
  easeInOutQuart: bezier(0.77, 0, 0.175, 1),
  easeInQuint: bezier(0.755, 0.05, 0.855, 0.06),
  easeOutQuint: bezier(0.23, 1, 0.32, 1),
  easeInOutQuint: bezier(0.86, 0, 0.07, 1),
  easeInExpo: bezier(0.95, 0.05, 0.795, 0.035),
  easeOutExpo: bezier(0.19, 1, 0.22, 1),
  easeInOutExpo: bezier(1, 0, 0, 1),
  easeInCirc: bezier(0.6, 0.04, 0.98, 0.335),
  easeOutCirc: bezier(0.075, 0.82, 0.165, 1),
  easeInOutCirc: bezier(0.785, 0.135, 0.15, 0.86),
  easeInBack: bezier(0.6, -0.28, 0.735, 0.045),
  easeOutBack: bezier(0.175, 0.885, 0.32, 1.275),
  easeInOutBack: bezier(0.68, -0.55, 0.265, 1.55),
  easeLinear: (n: number) => n,
}

const BoxWrapper = styled.div`
  display: flex;
  flex-direction: column;
  align-items: center;
`
const Box = styled.div`
  position: relative;
  border: 1px solid #555;
  height: ${BOX_SIZE}px;
  width: ${BOX_SIZE}px;
`

const Ball = styled.div`
  position: absolute;
  border-radius: 100%;
  background-color: #901a3b;
  width: ${BALL_SIZE}px;
  height: ${BALL_SIZE}px;
  left: ${BOX_SIZE / 2 - BALL_SIZE / 2}px;
`

const SelectWrapperLabel = styled.h2`
  margin-top: 2em;
  font-size: 0.8em;
`

const SelectWrapper = styled.div`
  display: flex;
  flex-wrap: wrap;
  flex-direction: row;
  input[type='checkbox'] {
    opacity: 0;
    position: absolute;
    height: 1px;
    width: 1px;
  }
  font-size: 90%;
  label {
    border-radius: 3px;
    padding: 0 2px;
    margin: 0 2px;
  }
  label:focus-within {
    color: #333;
    background-color: #ccc;
  }
  label.selected {
    background-color: #5588ee;
    color: #333;
  }
`

export default function App() {
  return <AnimationExample />
}
```

Extra npm dependencies used by this example: `bezier-easing`, `styled-components`.

---
title: React context
url: https://react-rx.dev/examples/context
---

```tsx filename="App.tsx"
import {useMemo} from 'react'
import {Subject} from 'rxjs'

import {
  ContextProvider,
  MODE,
  type Scheme,
  useModeValue,
} from './context'
import ModeSwitcher from './ModeSwitcher'

function App() {
  const mode = useModeValue()

  return (
    <div
      style={{
        ...MODE[mode],
        padding: '1em',
      }}
    >
      <h2>Using {mode} mode</h2>
      <ModeSwitcher />
    </div>
  )
}

function Layout() {
  const mode = useMemo(
    () => new Subject<Scheme>(),
    [],
  )

  return (
    <>
      <h1>Wrapped in ContextProvider</h1>
      <ContextProvider value={mode}>
        <App />
        <App />
      </ContextProvider>
      <hr />
      <h1>Not wrapped in a Context.Provider</h1>
      <App />
    </>
  )
}

export default Layout
```

```tsx filename="ModeSwitcher.tsx"
import {
  MODE,
  useModeValue,
  useSetMode,
} from './context'

export default function ModeSwitcher() {
  const mode = useModeValue()
  const handleModeChange = useSetMode()
  const next = mode === 'light' ? 'dark' : 'light'

  return (
    <button
      onClick={() => handleModeChange(next)}
      style={MODE[mode]}
    >
      Change to {next}
    </button>
  )
}
```

```tsx filename="context.tsx"
import {
  createContext,
  memo,
  useCallback,
  useContext,
} from 'react'
import {useObservable} from 'react-rx'
import {Subject} from 'rxjs'

export type Scheme = 'dark' | 'light'

const Context = createContext(
  new Subject<Scheme>(),
)

function ContextProviderComponent({
  children,
  value,
}: {
  children: React.ReactNode
  value: Subject<Scheme>
}) {
  return (
    <Context.Provider value={value}>
      {children}
    </Context.Provider>
  )
}
export const ContextProvider = memo(
  ContextProviderComponent,
)

export function useModeValue() {
  const observable = useContext(Context)

  return useObservable(
    observable,
    'light' satisfies Scheme,
  )
}

export function useSetMode() {
  const observable = useContext(Context)
  return useCallback(
    (value: Scheme) => {
      observable.next(value)
    },
    [observable],
  )
}

const LIGHT = {
  backgroundColor: '#eee',
  color: '#333',
}
const DARK = {
  backgroundColor: '#222',
  color: '#eee',
}

export const MODE = {
  light: LIGHT,
  dark: DARK,
}
```

---
title: Sync rendering
url: https://react-rx.dev/examples/sync
---

```tsx filename="App.tsx"
import {useObservable} from 'react-rx'
import {from} from 'rxjs'

const observable = from([
  'This',
  'will',
  'only',
  'render',
  'once!',
])

function Sync() {
  const message = useObservable(observable)

  return <>{message}</>
}

export default Sync
```

---
title: Suspense & deferred values
url: https://react-rx.dev/examples/suspense
---

# Suspense & deferred values

Type into the search field and watch the two panels side by side.

- **Left (`useSyncObservable`)** — each keystroke is a synchronous store update. When results suspend, React replaces already-visible content with the Suspense fallback (and may log _“A component suspended while responding to synchronous input”_ — open Sandpack’s console).
- **Right (`useObservable`)** — store updates are deferred. Already-revealed results stay on screen (dimmed while stale) until the new ones are ready.
- **The input itself** reads `useSyncObservable` so typing never lags — this is exactly when you need the sync hook.

```tsx filename="App.tsx"
import {ChangeEvent, Suspense, use} from 'react'
import {
  useObservable,
  useObservableEvent,
  useSyncObservable,
} from 'react-rx'
import {map, Subject, tap} from 'rxjs'

// Shared by the input and both panels. Each hook file has its own
// WeakMap, so dual reads subscribe twice — fine for this demo.
const keyword$ = new Subject<string>()

type CacheEntry = {
  promise: Promise<string[]>
  value?: string[]
}

const resultsCache = new Map<string, CacheEntry>()

function searchHits(
  keyword: string,
): Promise<string[]> {
  let entry = resultsCache.get(keyword)
  if (!entry) {
    entry = {
      promise: new Promise((resolve) => {
        // Shorter keywords take longer — mirrors the search example.
        const delay = Math.max(
          200,
          (10 - keyword.length) * 80,
        )
        setTimeout(() => {
          const hits = Array.from(
            {length: Math.max(1, keyword.length)},
            (_, i) =>
              `Hit #${i + 1} for “${keyword}”`,
          )
          entry!.value = hits
          resolve(hits)
        }, delay)
      }),
    }
    resultsCache.set(keyword, entry)
  }
  return entry.promise
}

function SlowResults({
  keyword,
}: {
  keyword: string
}) {
  if (!keyword) {
    return (
      <p>Type to search — results suspend.</p>
    )
  }
  // use() suspends until the promise resolves (same idea as throwing a promise).
  const hits = use(searchHits(keyword))
  return (
    <ul>
      {hits.map((hit) => (
        <li key={hit}>{hit}</li>
      ))}
    </ul>
  )
}

function SyncPanel() {
  const keyword = useSyncObservable(keyword$, '')
  return (
    <section
      style={{
        flex: 1,
        border: '1px solid #ccc',
        padding: 12,
      }}
    >
      <h3>useSyncObservable</h3>
      <p style={{fontSize: 13, opacity: 0.8}}>
        Synchronous store updates. Typing discards
        visible results and shows the Suspense
        fallback (also logs React’s “suspended
        while responding to synchronous input”
        warning — open the console).
      </p>
      <Suspense
        fallback={<p>Loading results…</p>}
      >
        <SlowResults keyword={keyword} />
      </Suspense>
    </section>
  )
}

function DeferredPanel() {
  const keyword = useObservable(keyword$, '')
  // Dual read for the isStale dimming pattern (two module caches).
  const syncKeyword = useSyncObservable(
    keyword$,
    '',
  )
  const isStale = keyword !== syncKeyword
  return (
    <section
      style={{
        flex: 1,
        border: '1px solid #ccc',
        padding: 12,
        opacity: isStale ? 0.5 : 1,
      }}
    >
      <h3>useObservable</h3>
      <p style={{fontSize: 13, opacity: 0.8}}>
        Deferred store updates. Previous results
        stay on screen (dimmed while stale) until
        the new ones are ready — no fallback
        flash.
      </p>
      <Suspense
        fallback={<p>Loading results…</p>}
      >
        <SlowResults keyword={keyword} />
      </Suspense>
    </section>
  )
}

export default function App() {
  // Controlled input value must update synchronously.
  const keyword = useSyncObservable(keyword$, '')
  const handleInput = useObservableEvent<
    ChangeEvent<HTMLInputElement>,
    any
  >((input$) =>
    input$.pipe(
      map((e) => e.currentTarget.value),
      tap((value) => keyword$.next(value)),
    ),
  )

  return (
    <div>
      <input
        type="search"
        style={{width: '100%', marginBottom: 12}}
        value={keyword}
        placeholder="Type a keyword"
        onChange={handleInput}
      />
      <div
        style={{
          display: 'flex',
          gap: 12,
          alignItems: 'flex-start',
        }}
      >
        <SyncPanel />
        <DeferredPanel />
      </div>
    </div>
  )
}
```

## Why this happens

[`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore#caveats) cannot mark store mutations as Transitions, so suspending on its value triggers the nearest Suspense fallback. Wrapping the value in [`useDeferredValue`](https://react.dev/reference/react/useDeferredValue) (what `useObservable` does) is how you [prevent unwanted fallbacks](https://react.dev/reference/react/Suspense#preventing-unwanted-fallbacks) for already-revealed content.

See also [jantimon/react-hydration-rules](https://github.com/jantimon/react-hydration-rules) for the broader hydration/Suspense matrix, and the React reconciler tests for `useDeferredValue` / `useSyncExternalStore` in [facebook/react](https://github.com/facebook/react). Hydration-time differences between the two hooks are covered by the library’s Vitest suite (Sandpack examples are client-only).

---
title: Suspense data fetching
url: https://react-rx.dev/examples/data-fetching
---

# Suspense data fetching

`useObservablePromise` returns a promise for React's `use()`. The Suspense
fallback shows until the first emission; later stream updates do not re-trigger
it.

```tsx filename="App.tsx"
import {Suspense, use, useState} from 'react'
import {
  useObservablePromise,
  type ObservablePromise,
} from 'react-rx'
import {map, type Observable, timer} from 'rxjs'

const LATENCY_MS = 800

const userCache = new Map<
  string,
  Observable<{
    id: string
    name: string
    bio: string
  }>
>()

/** Stable per id so Suspense retries and remounts share one in-flight request. */
function fetchUser$(id: string) {
  let observable = userCache.get(id)
  if (!observable) {
    observable = timer(LATENCY_MS).pipe(
      map(() => ({
        id,
        name:
          id === 'alpha'
            ? 'Ada Lovelace'
            : 'Grace Hopper',
        bio: `Profile loaded for ${id}`,
      })),
    )
    userCache.set(id, observable)
  }
  return observable
}

const clock$ = timer(0, 1000).pipe(
  map(
    (n) =>
      `Tick ${n} — live updates skip the Suspense fallback`,
  ),
)

function Profile({
  promise,
}: {
  promise: ObservablePromise<{
    id: string
    name: string
    bio: string
  }>
}) {
  const user = use(promise)
  return (
    <div>
      <h3>{user.name}</h3>
      <p>{user.bio}</p>
    </div>
  )
}

function LiveClock() {
  const label = use(useObservablePromise(clock$))
  return (
    <p style={{fontSize: 14, opacity: 0.8}}>
      {label}
    </p>
  )
}

export default function DataFetchingExample() {
  const [id, setId] = useState('alpha')
  // Create the promise in a parent that does not suspend, so Suspense retries
  // always see the same promise identity (see React's use() caching guidance).
  const promise = useObservablePromise(
    fetchUser$(id),
  )

  return (
    <div
      style={{
        fontFamily: 'system-ui',
        padding: 16,
      }}
    >
      <p>
        <button
          type="button"
          onClick={() => setId('alpha')}
        >
          alpha
        </button>{' '}
        <button
          type="button"
          onClick={() => setId('beta')}
        >
          beta
        </button>
      </p>
      <Suspense
        key={id}
        fallback={
          <p style={{opacity: 0.7}}>
            Loading {id}…
          </p>
        }
      >
        <Profile promise={promise} />
      </Suspense>
      <hr style={{margin: '16px 0'}} />
      <Suspense fallback={null}>
        <LiveClock />
      </Suspense>
      <p
        style={{
          marginTop: 16,
          fontSize: 14,
          opacity: 0.75,
        }}
      >
        Switching profiles re-suspends (new
        observable). The clock updates
        continuously without flashing a fallback.
      </p>
    </div>
  )
}
```

---
title: Activity and preload
url: https://react-rx.dev/examples/activity
---

# Activity and preload

Compare three strategies for the same ~1s tab fetch:

1. **No prefetch** — mount on click; Suspense fallback is visible
2. **Hover preload** — `preloadObservablePromise` on `mouseenter` warms the cache
3. **Activity pre-render** — hidden `<Activity>` starts `use(promise)` fetches up front

```tsx filename="App.tsx"
import {
  Activity,
  Suspense,
  useMemo,
  useState,
} from 'react'
import {preloadObservablePromise} from 'react-rx'

import {fetchTab$} from './api'
import TabPanel from './TabPanel'

type Strategy = 'none' | 'preload' | 'activity'

const TABS = [
  'Posts',
  'Photos',
  'Settings',
] as const

function TabButton({
  tab,
  active,
  strategy,
  onSelect,
}: {
  tab: (typeof TABS)[number]
  active: boolean
  strategy: Strategy
  onSelect: () => void
}) {
  const data$ = useMemo(
    () => fetchTab$(tab),
    [tab],
  )

  return (
    <button
      type="button"
      onMouseEnter={() => {
        if (strategy === 'preload') {
          void preloadObservablePromise(data$, {
            ttl: 10_000,
          })
        }
      }}
      onClick={onSelect}
      style={{fontWeight: active ? 700 : 400}}
    >
      {tab}
    </button>
  )
}

export default function App() {
  const [strategy, setStrategy] =
    useState<Strategy>('none')
  const [active, setActive] =
    useState<(typeof TABS)[number]>('Posts')

  return (
    <div
      style={{
        fontFamily: 'system-ui',
        padding: 16,
        maxWidth: 480,
      }}
    >
      <h2 style={{marginTop: 0}}>
        Prefetch strategies
      </h2>
      <p style={{fontSize: 14}}>
        Each tab fetch takes ~1s. Compare
        click-only loading vs hover preload vs
        hidden <code>Activity</code> pre-render.
      </p>

      <label
        style={{
          display: 'block',
          marginBottom: 12,
        }}
      >
        Strategy:{' '}
        <select
          value={strategy}
          onChange={(e) =>
            setStrategy(
              e.target.value as Strategy,
            )
          }
        >
          <option value="none">
            No prefetch (fetch on reveal)
          </option>
          <option value="preload">
            Hover preload
          </option>
          <option value="activity">
            Activity pre-render
          </option>
        </select>
      </label>

      <div
        style={{
          display: 'flex',
          gap: 8,
          marginBottom: 16,
        }}
      >
        {TABS.map((tab) => (
          <TabButton
            key={tab}
            tab={tab}
            active={active === tab}
            strategy={strategy}
            onSelect={() => setActive(tab)}
          />
        ))}
      </div>

      <Suspense
        fallback={
          <p style={{opacity: 0.7}}>
            🌀 Loading…
          </p>
        }
      >
        {strategy === 'activity' ? (
          TABS.map((tab) => (
            <Activity
              key={tab}
              mode={
                active === tab
                  ? 'visible'
                  : 'hidden'
              }
            >
              <TabPanel tab={tab} />
            </Activity>
          ))
        ) : (
          <TabPanel tab={active} />
        )}
      </Suspense>
    </div>
  )
}
```

```tsx filename="TabPanel.tsx"
import {use} from 'react'
import {useMemo} from 'react'
import {useObservablePromise} from 'react-rx'

import {fetchTab$} from './api'

export default function TabPanel({
  tab,
}: {
  tab: string
}) {
  const data$ = useMemo(
    () => fetchTab$(tab),
    [tab],
  )
  const data = use(useObservablePromise(data$))

  return (
    <div
      style={{
        padding: 12,
        border: '1px solid #ccc',
        borderRadius: 8,
      }}
    >
      <strong>{data.tab}</strong>
      <p>{data.body}</p>
    </div>
  )
}
```

```ts filename="api.ts"
import {map, type Observable, timer} from 'rxjs'

const LATENCY_MS = 1000

const cache = new Map<
  string,
  Observable<{tab: string; body: string}>
>()

/** Cold fetch-like source with visible artificial latency. Stable per tab id. */
export function fetchTab$(
  tab: string,
): Observable<{tab: string; body: string}> {
  let observable = cache.get(tab)
  if (!observable) {
    observable = timer(LATENCY_MS).pipe(
      map(() => ({
        tab,
        body: `Content for “${tab}” loaded after ${LATENCY_MS}ms`,
      })),
    )
    cache.set(tab, observable)
  }
  return observable
}
```

---
title: Event Handlers
url: https://react-rx.dev/examples/event-handlers
---

```tsx filename="App.tsx"
import {MouseEvent, useMemo} from 'react'
import {useObservable} from 'react-rx'
import {map, startWith, Subject} from 'rxjs'

// Create subject for mouse moves
const mouseMove$ = new Subject<MouseEvent>()

function EventHandlersExample() {
  // Create mouse position stream
  const position$ = useMemo(
    () =>
      mouseMove$.pipe(
        map((event) => ({
          x: event.clientX,
          y: event.clientY,
        })),
        startWith(null),
      ),
    [],
  )

  const position = useObservable(position$, null)

  return (
    <div
      style={{
        display: 'flex',
        alignItems: 'center',
        textAlign: 'center',
        height: 150,
        width: 150,
        border: '1px dashed',
        padding: '1em',
      }}
      onMouseMove={(event) =>
        mouseMove$.next(event)
      }
    >
      <div
        style={{
          width: '100%',
        }}
      >
        {position ? (
          <>
            Cursor position: X:
            {position.x}, Y: {position.y}
          </>
        ) : (
          <>Move mouse here</>
        )}
      </div>
    </div>
  )
}

export default EventHandlersExample
```

---
title: Fetch
url: https://react-rx.dev/examples/fetch
---

```tsx filename="App.tsx"
import {useMemo} from 'react'
import {
  useObservable,
  useObservableEvent,
} from 'react-rx'
import {
  distinctUntilChanged,
  map,
  Subject,
  switchMap,
  tap,
} from 'rxjs'

// Create subject for URL changes
const url$ = new Subject<string>()

const origin = new URL('https://react-rx.sanity.dev')
const URLS = [
  new URL('/fetch/a.txt', origin),
  new URL('/fetch/b.txt', origin),
]

function FetchExample() {
  // Handle URL selection
  const handleUrlClick = useObservableEvent<
    string,
    any
  >((click$) =>
    click$.pipe(tap((url) => url$.next(url))),
  )

  // Create fetch response stream
  const response$ = useMemo(
    () =>
      url$.pipe(
        distinctUntilChanged(),
        switchMap((url) =>
          fetch(url).then((response) =>
            response.text(),
          ),
        ),
        map((responseText) => (
          <div>
            The result was: {responseText}
          </div>
        )),
      ),
    [],
  )

  const currentUrl = useObservable(url$, '')
  const response = useObservable(response$)

  return (
    <div>
      <p>
        {URLS.map((url) => (
          <button
            key={url.toString()}
            onClick={() =>
              handleUrlClick(url.toString())
            }
          >
            {url.pathname}
          </button>
        ))}
      </p>
      {currentUrl ? (
        response
      ) : (
        <>Click on url to fetch</>
      )}
    </div>
  )
}

export default FetchExample
```

---
title: Form Data
url: https://react-rx.dev/examples/form-data
---

```tsx filename="App.tsx"
import {
  ChangeEvent,
  type SyntheticEvent,
  useState,
} from 'react'
import {
  useObservable,
  useObservableEvent,
  useSyncObservable,
} from 'react-rx'
import {
  type Observable,
  map,
  scan,
  startWith,
  Subject,
  switchMap,
  tap,
  withLatestFrom,
} from 'rxjs'
import {styled} from 'styled-components'

import storage from './storage'

const STORAGE_KEY = '__form-submit-example__'

// Create subjects for form events
const formData$ = new Subject<
  Partial<FormValues>
>()
const submit$ = new Subject<
  SyntheticEvent<HTMLFormElement>
>()

interface FormValues {
  title: string
  description: string
}

function FormDataExample() {
  // Handle input changes
  const handleChange = useObservableEvent<
    ChangeEvent<
      HTMLInputElement | HTMLTextAreaElement
    >,
    any
  >((change$) =>
    change$.pipe(
      map((event) => ({
        [event.target.name]: event.target.value,
      })),
      tap((update) => formData$.next(update)),
    ),
  )

  // Handle form submissions
  const handleSubmit = useObservableEvent<
    SyntheticEvent<HTMLFormElement>,
    any
  >((event$) =>
    event$.pipe(
      tap((e) => {
        e.preventDefault()
        submit$.next(e)
      }),
    ),
  )

  // Create form data stream
  const [data$] = useState(() =>
    storage
      .get(STORAGE_KEY, {
        title: '',
        description: '',
      })
      .pipe(
        switchMap((initial) =>
          formData$.pipe(
            startWith(initial),
            scan(
              (data, update) => ({
                ...data,
                ...update,
              }),
              initial,
            ),
          ),
        ),
      ),
  )

  // Create submit state stream
  const [submitState$] = useState(() =>
    submit$.pipe(
      withLatestFrom(data$),
      map(([, formData]) => formData),
      map((formData) =>
        storage.set(STORAGE_KEY, formData).pipe(
          map(() => ({
            status: 'saved' as const,
            result: formData,
          })),
          startWith({
            status: 'saving' as const,
            result: null,
          }),
        ),
      ),
      startWith({
        status: 'unsaved' as const,
        result: null,
      }),
    ),
  )

  // Form field values feed controlled inputs — must stay synchronous.
  const formData = useSyncObservable(data$, {
    title: '',
    description: '',
  })
  const submitState = useObservable(
    // @TODO investigate why this is necessary
    submitState$ as unknown as Observable<{
      status: 'saved' | 'saving' | 'unsaved'
      result: FormValues | null
    }>,
    {
      status: 'unsaved' as const,
      result: null,
    },
  )

  return (
    <Form onSubmit={handleSubmit}>
      <div>
        <label>
          <strong>Title: </strong>
          <input
            type="text"
            name="title"
            value={formData.title}
            onChange={handleChange}
          />
        </label>
      </div>
      <div>
        <label>
          <strong>Description: </strong>
          <textarea
            name="description"
            value={formData.description}
            onChange={handleChange}
          />
        </label>
      </div>
      <div>
        <button
          disabled={
            submitState.status === 'saving'
          }
        >
          {submitState.status === 'saving'
            ? 'Saving…'
            : submitState.status === 'saved'
              ? 'Saved!'
              : 'Save'}
        </button>
      </div>
    </Form>
  )
}

const Form = styled.form`
  label {
    display: block;
    margin-top: 10px;
  }
  input,
  textarea {
    box-sizing: border-box;
    width: 100%;
    padding: 5px;
  }
`

export default FormDataExample
```

```ts filename="storage.ts"
import {Observable, of} from 'rxjs'

const tryParse = <T>(
  val: any,
  defaultValue: T,
): T => {
  try {
    return JSON.parse(val)
  } catch {
    return defaultValue
  }
}

const get = <T>(
  key: string,
  defValue: T,
): Observable<T> => {
  const val = localStorage.getItem(key)
  return of(
    val === null
      ? defValue
      : tryParse<T>(val, defValue),
  )
}

const set = <T>(
  key: string,
  nextValue: T,
): Observable<T> => {
  // Can't stringify undefined, and nulls are what
  // `getItem` returns when key does not exist
  if (
    typeof nextValue === 'undefined' ||
    nextValue === null
  ) {
    localStorage.removeItem(key)
  } else {
    localStorage.setItem(
      key,
      JSON.stringify(nextValue),
    )
  }
  return of(nextValue)
}

export default {get, set}
```

Extra npm dependencies used by this example: `styled-components`.

---
title: Search
url: https://react-rx.dev/examples/search
---

```tsx filename="App.tsx"
import {ChangeEvent, useMemo} from 'react'
import {
  useObservable,
  useObservableEvent,
  useSyncObservable,
} from 'react-rx'
import {
  distinctUntilChanged,
  filter,
  map,
  Observable,
  Subject,
  switchMap,
  tap,
  timer,
} from 'rxjs'

interface SearchResult {
  keyword: string
  hits: Hit[]
}

interface Hit {
  title: string
}

const range = (len: number) => {
  const res: null[] = []
  for (let i = 0; i <= len; i++) {
    res.push(null)
  }
  return res
}

// Create subject for search input
const keyword$ = new Subject<string>()

// A search function that takes longer time to complete for shorter keywords
const search = (
  keyword: string,
): Observable<SearchResult> => {
  const delay = Math.max(
    1,
    Math.round(10 - keyword.length),
  )
  return timer(delay * 200).pipe(
    map(() =>
      range(delay).map((_, i) => ({
        title: `Hit #${i}`,
      })),
    ),
    map((hits) => ({
      keyword,
      hits,
    })),
  )
}

function SearchExample() {
  // Handle input changes
  const handleInput = useObservableEvent<
    ChangeEvent<HTMLInputElement>,
    any
  >((input$) =>
    input$.pipe(
      map((e) => e.currentTarget.value),
      tap((value) => keyword$.next(value)),
    ),
  )

  // Create search results stream
  const results$ = useMemo(
    () =>
      keyword$.pipe(
        distinctUntilChanged(),
        filter((v) => v !== ''),
        switchMap((kw: string) => search(kw)),
        map((result: SearchResult) => (
          <>
            <h1>Searched for {result.keyword}</h1>
            <div>
              Got {result.hits.length} hits
            </div>
            <ul>
              {result.hits.map((hit) => (
                <li key={hit.title}>
                  {hit.title}
                </li>
              ))}
            </ul>
          </>
        )),
      ),
    [],
  )

  // Controlled input value must update synchronously.
  const keyword = useSyncObservable(keyword$, '')
  // Results are deferred by default via useObservable (no manual useDeferredValue).
  const results = useObservable(results$)

  return (
    <>
      <input
        type="search"
        style={{width: '100%'}}
        value={keyword}
        placeholder="Type a keyword to search"
        onChange={handleInput}
      />
      <div>
        The more characters you type, the faster
        the results will appear
      </div>
      {results}
    </>
  )
}

export default SearchExample
```