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
• Package dependencies

Examples

Hooks

import { Suspense } from "react";
import { 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"]}
      render={({ 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 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: string|object (optional)

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

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

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

options: object

Options to find.

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])

db: string|object

Override 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 context to other components and hooks.

name: string

maxListeners: number

Similar change requests are pooled, but you might still need to increase the number of maxListeners.

...rest: any

Other props are passed to PouchDB constructor as second argument.

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

<Get>

Get document and listen to changes.

db: string|object

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

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

id: string

docId.

component

Component is rendered with props db and doc when the initial request completes and when the document is updated. If the document is not found, doc is undefined.

<Get id="mydoc" component={Title} />

render: func

render function is called with props db and doc when the initial request completes and when the document is updated. If the document is not found, doc is undefined.

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

children: func|element

Render while the request is pending, completed and document is updated. Function is called / component is rendered / element is cloned with props db and doc.

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

attachments: bool|string

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

<Get
  attachments
  id="mydoc"
  render={({ 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

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

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

selector: object

sort: array

limit: number

skip: number

See find.

component

render: func

children: func|element

Render props are as in <Get> component. Render methods will be passed db and docs props.

<Find
  selector={{
    name: { $gte: null }
  }}
  sort={["name"]}
  render={({ 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>
));

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.

Changelog

1.0.0

• Add Hooks API
• Add optional db prop to <Get> and <Find>
• Breaking change: remove exists prop from <Get> render methods. Use !!doc
• Breaking change: remove attachment prop from <Get> render methods. Use doc._attachments
• Breaking change: component and render render props require the use of <Suspense> as a parent component
• Breaking change: <Get> render props are called even if document does not exist
• Update DB connection when <PouchDB /> props change
• Fix infinite suspense loop if database request throws error
• Update dependencies