react-pouchdb

React wrapper for PouchDB that also subscribes to changes.

TodoMVC example

Contents

• Examples
  • Hooks
  • Components
• API
  • useGet
  • useFind
  • useAllDocs
  • useDB
  • <PouchDB>
  • <Get>
  • <Find>
  • <AllDocs>
  • 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 id, 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.

options.sort: (string|object)[] (optional)

If sort is present, then it will be used to create a mango index with createIndex.

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>
  );
}

useAllDocs([db,] options)

Get multiple rows of document meta-data (id and rev) with optional the documents and listen to changes.

db: string|object (optional)

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

options: object

Options to allDocs.

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
Array	List of document meta data with the document. The rows-field from allDocs.	[{"id": "doc_id", "key": "doc_id", "value": { "rev": ... }, "doc": { ... } }, ...]

import { useAllDocs } from "react-pouchdb";
 
function MyComponent() {
  const rows = useAllDocs({
    include_docs: true,
    startkey: "profile_",
    endkey: "profile_\uffff"
  });
  return (
    <ul>
      {rows.map(row => (
        <li key={row.id}>{row.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

If sort is present, then it will be used to create a mango index with createIndex.

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>
  )}
/>

<AllDocs>

Get multiple rows of document meta-data (id and rev) with optional the documents and listen to changes.

db: string|object (optional)

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

<AllDocs db="dbname" include_docs ... />

include_docs: bool

conflicts: bool

attachments: bool|string

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

startkey: string

endkey: string

descending: bool

keys: string[]

limit: number

skip: number

See allDocs.

children: func|component|element

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

<AllDocs
  include_docs
  startkey="profile_"
  endkey="profile_\uffff"
  children={({ rows }) => (
    <ul>
      {rows.map(row => (
        <li key={doc.id}>{row.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.