react-pouchdb

react-pouchdb

React wrapper for PouchDB that also subscribes to changes.

TodoMVC example

Contents

• Examples
  • Hooks
  • Components
• API
  • useGet
  • useFind
  • useDB
  • <PouchDB>
  • <Get>
  • <Find>
  • withDB
• API Variants
  • Synchronous
  • Concurrent
• Package dependencies

Examples

Hooks

import { Suspense } from "react";
import { PouchDB, useFind, useDB } from "react-pouchdb";

function MyComponent() {
  const docs = useFind({
    selector: {
      name: { $gte: null }
    },
    sort: ["name"]
  });
  const db = useDB();

  return (
    <ul>
      {docs.map(doc => (
        <li key={doc._id}>
          {doc.name}
          <button onClick={() => db.remove(doc)}>Remove</button>
        </li>
      ))}
    </ul>
  );
}

<PouchDB name="dbname">
  <Suspense fallback="loading...">
    <MyComponent />
  </Suspense>
</PouchDB>;

Components

import { Suspense } from "react";
import { PouchDB, Find } from "react-pouchdb";

<PouchDB name="dbname">
  <Suspense fallback="loading...">
    <Find
      selector={{
        name: { $gte: null }
      }}
      sort={["name"]}
      children={({ db, docs }) => (
        <ul>
          {docs.map(doc => (
            <li key={doc._id}>
              {doc.name}
              <button onClick={() => db.remove(doc)}>Remove</button>
            </li>
          ))}
        </ul>
      )}
    />
  </Suspense>
</PouchDB>;

API

useGet([db,] options)

Get document and listen to changes.

db: string|object (optional)

Override the context value or use as an alternative to <PouchDB>.

options: object

Options to get. If other than attachments, ajax or binary options are set, live changes are disabled.

options.attachments: bool|string (optional)

Include document attachments. Set to "u8a" to get attachments as Uint8Arrays.

Returns

Value	Description	Example
undefined	Request is pending (only in Concurrent API)	undefined
null	Missing document	null
Document	Found document	{"_id": ..., "_rev": ..., ...}
Deleted document	Deleted document	{"_id": ..., "_rev": ..., "_deleted": true}

import { useGet } from "react-pouchdb";

function MyComponent() {
  const doc = useGet({ id: "mydoc" });
  return <div>{doc.name}</div>;
}

useFind([db,] options)

Find documents and listen to changes.

db: string|object (optional)

Override the context value or use as an alternative to <PouchDB>.

options: object

Options to find.

Returns

Value	Description	Example
undefined	Request is pending (only in Concurrent API)	undefined
Array	List of documents	[{"_id": ..., "_rev": ..., ...}, ...]

import { useFind } from "react-pouchdb";

function MyComponent() {
  const docs = useFind({
    selector: {
      name: { $gte: null }
    },
    sort: ["name"]
  });
  return (
    <ul>
      {docs.map(doc => (
        <li key={doc._id}>{doc.name}</li>
      ))}
    </ul>
  );
}

useDB([db])

Get the PouchDB instance from the context.

db: string|object (optional)

Override the context value or use as an alternative to <PouchDB>.

import { useDB } from "react-pouchdb";

function MyComponent({ title }) {
  const db = useDB();
  return <button onClick={() => db.post({ title })}>Add</button>;
}

<PouchDB>

Connect to a database and provide it from the context to other components and hooks.

name: string

maxListeners: number

Similar change requests are detected and cached. You might still need to increase the number of maxListeners, if you use useGet / <Get> with lots of different options.

...rest: any

Other props are passed to PouchDB constructor as a second argument.

<PouchDB name="dbname">
  <App />
</PouchDB>

<Get>

Get document and listen to changes.

db: string|object (optional)

Override the context value or use as an alternative to <PouchDB>.

<Get db="dbname" id="mydoc" ... />

id: string

docId.

children: func|component|element

Function is called / component is rendered / element is cloned with props db and doc. See useGet return value for possible values for doc.

<Get id="mydoc" children={({ doc }) => <h1>{doc.title}</h1>} />

attachments: bool|string

Include document attachments. Set to "u8a" to get attachments as Uint8Arrays.

<Get
  attachments
  id="mydoc"
  children={({ doc }) => (
    <>
      <h1>{doc.title}</h1>
      <code>{doc._attachments["att.txt"].data}</code>
    </>
  )}
/>

...rest: any

Other props are passed to get method as second argument. If other than attachments, ajax or binary props are provided, live changes are disabled.

<Find>

Find documents and listen to changes.

db: string|object (optional)

Override the context value or use as an alternative to <PouchDB>.

<Find db="dbname" selector={...} ... />

selector: object

sort: array

limit: number

skip: number

See find.

children: func|component|element

Function is called / component is rendered / element is cloned with props db and docs. See useFind return value for possible values for docs.

<Find
  selector={{
    name: { $gte: null }
  }}
  sort={["name"]}
  children={({ docs }) => (
    <ul>
      {docs.map(doc => (
        <li key={doc._id}>{doc.name}</li>
      ))}
    </ul>
  )}
/>

withDB([db,] Component)

Higher-order component for accessing the PouchDB instance anywhere in the <PouchDB> children. Note that for convenience <Get> and <Find> render methods will be passed the db prop as well.

import { withDB } from "react-pouchdb";

const MyComponent = withDB(({ db, title }) => (
  <button onClick={() => db.post({ title })}>Add</button>
));

API Variants

Synchronous

It is guaranteed that the API returns with a final response value from PouchDB. Because of this, requests are made sequentially.

Import from react-pouchdb to use the Synchronous API. Example:

import { useFind, useDB } from "react-pouchdb";

Concurrent

Requests are made simultaneously. The drawback is that while a request is pending, the API returns undefined, which user must handle without error, i.e. render null and use <Suspense> to show a loading indicator.

Import from react-pouchdb/concurrent to use the Concurrent API. Example:

import { useFind, useDB } from "react-pouchdb/concurrent";

Package dependencies

The package expects pouchdb to be available. If you use pouchdb-browser or pouchdb-node, import from react-pouchdb/browser or react-pouchdb/node respectively.

If you use pouchdb-browser or pouchdb-node and Concurrent API, import from react-pouchdb/browser/concurrent or react-pouchdb/node/concurrent.

Changelog

2.0.0-beta.3

• Use use-subscription