Skip to content
⚛️☯️💪 React hooks for RxJS Observables.
TypeScript JavaScript
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples docs: remove deprecated code Aug 21, 2019
scripts docs: add gzipped size Sep 1, 2019
src docs: add notes on closure Nov 11, 2019
test perf: faster useObservable without inputs Sep 1, 2019
.editorconfig build: init Jul 17, 2019
.eslintrc.js build: init Jul 17, 2019
.gitignore docs: add pomodoro timer example Jul 23, 2019
.prettierrc build: init Jul 17, 2019
.travis.yml ci: upload coverage after success Jul 23, 2019 chore(release): 2.1.2 Sep 7, 2019
LICENSE build: init Jul 17, 2019 docs: add conditional rendering example Nov 11, 2019
commitlint.config.js chore: add commit styles Jul 21, 2019
jest.config.js test: add jest testing Jul 21, 2019
package.json chore(release): 2.1.2 Sep 7, 2019
tsconfig.json build: target esnext Aug 31, 2019
typedoc.json feat: add helpers Jul 20, 2019
yarn.lock docs: add gzipped size Sep 1, 2019


npm-version Build Status Coverage Status

Commitizen friendly Conventional Commits JavaScript Style Guide code style: prettier

React hooks for RxJS Observables with powerful APIs.

  • Seamless integration of React and RxJS.
    • Props and states to Observables?
    • Observables to props events?
    • Async "setState"?
    • Stream of React Components???
  • Full-powered RxJS. Do whatever you want with Observables. No limitation or compromise.
  • Fully tested.
  • Lightweight and fast. 741 B compressed & gzipped. A lot of efforts had been put into improving integration. This library should have zero visible impact on performance.


React added hooks for reusing stateful logic. Observable is a powerful way to encapsulate both sync and async logic. And testing Observables is way easier than testing other async implementations in a React Component.

Now we can reuse Observable logic joyfully with observable-hooks.

What It Is Not

This library is not for replacing state management tools like Redux (though technically it could with its flexible APIs plus other hooks) but to reduce the need of dumping everything into global state just because there used to be no better way to handle it inside React Components.

Using this library does not mean you have to turn everything observable. It is not encouraged to abuse Observables. It plays well side by side with other hooks. Use it only on places where it's needed.

At a Glance

import * as React from 'react'
import { useObservableState } from 'observable-hooks'
import { timer } from 'rxjs'
import { switchMap, mapTo, startWith } from 'rxjs/operators'

const App = () => {
  const [isTyping, updateIsTyping] = useObservableState(

  return (
      <input type="text" onKeyDown={updateIsTyping} />
      <p>{isTyping ? 'Good you are typing.' : 'Why stop typing?'}</p>

// Logic can be tested like Epic in redux-observable
function transformTypingStatus(event$) {
  return event$.pipe(
    switchMap(() =>



yarn add observable-hooks


npm install --save observable-hooks


Read the docs here.

Here is how I designed the APIs. Might give you a perspective on when use what.


Examples are in here. Play on CodeSandbox:

Note that there are also some useful utilities for common use cases to reduce garbage collection.

All available APIs can be imported from the entry.

import { ... } from 'observable-hooks'

Overly Simplified Examples

Conditional rendering (with vanilla JavaScript)

With observable-hooks you can have a stream of React Components which is like Suspense but armed with the incredible RxJS operators.

import { from, of } from 'rxjs'
import { map, switchMap, startWith, catchError } from 'rxjs/operators'
import { useObservableState } from 'observable-hooks'
import { fetchData } from './api'
import { SuccessUI, LoadingUI, ErrorUI } from './components'

export function App() {
  const [status, onFetchData] = useObservableState(
    event$ => event$.pipe(
      // initial fetching
      // OMG I don't have to deal with race condition
      switchMap(event =>
        from(fetchData(event &&
          map(value => <SuccessUI value={value} />),
          startWith(<LoadingUI />)
      catchError(error => of(<ErrorUI error={error} />))

  return (
      <button id="data1" onClick={onFetchData}>fetch</button>

Debounce Text Verification (with vanilla JavaScript)

import React from 'react'
import PropTypes from 'prop-types'
import { withLatestFrom, switchMap, debounceTime, pluck } from 'rxjs/operators'
import { useObservable, useObservableState, pluckFirst } from 'observable-hooks'

const checkText = (text, uuid) =>
    .then(response => response.ok)
    .catch(() => false)

export const App = props => {
  // `pluckFirst` is a simple helper function to avoid garbage collection,
  // equivalent to `inputs$ => inputs$.pipe(map(inputs => inputs[0]))`
  const uuid$ = useObservable(pluckFirst, [props.uuid])

  const [isValid, onChange] = useObservableState(
    event$ =>
        // React synthetic event object will be reused.
        // Pluck the value out first.
        pluck('currentTarget', 'value'),
        switchMap(([text, uuid]) => checkText(text, uuid))

  return (
      <input onChange={onChange} />
      <button type="submit" disabled={!isValid}>

App.propTypes = {
  uuid: PropTypes.string

Auto-cancelation (with TypeScript)

import React, { FC, useState } from 'react'
import { timer, empty } from 'rxjs'
import { switchMap, mapTo } from 'rxjs/operators'
import { useObservable, useSubscription } from 'observable-hooks'

const sendBeacon = (beacon: string) => fetch(`https://api?beacon=${beacon}`)

export interface AppProps {
  beacon: string

export const App: FC<AppProps> = props => {
  const [shouldSendBeacon, setShouldSendBeacon] = useState(false)

  const beacon$ = useObservable(
    inputs$ =>
        // auto-cancelation
        switchMap(([shouldSendBeacon, beacon]) =>
          shouldSendBeacon ? timer(1000).pipe(mapTo(beacon)) : empty()
    // `as const` is a simple way to make an array tuple.
    // You can also use `as [boolean, string]` or `as [typeof xxx, typeof xxx]`
    [shouldSendBeacon, props.beacon] as const

  useSubscription(beacon$, sendBeacon)

  return (
        onChange={e => setShouldSendBeacon(e.currentTarget.checked)}
      Should Send Beacon
You can’t perform that action at this time.