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

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

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

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.