useDoc
Overview
To read a single document use useDoc
. It is the hook version of
db.get()
. It also subscripts to updates for that document.
useDoc
can only be invoked from a component nested inside of a <Provider />
.
Parameters
useDoc
has the same options as db.get()
, with the only exception
of options.open_revs
not being supported. Options descriptions are copied from the PouchDB API page.
id: string
- _id of the document.options?: object | null
-db.get()
option object. All options exceptoptions.open_revs
are allowed.options.rev?: string
- If set: fetch specific revision of a document. It defaults to winning revision.options.revs?: boolean
- Include revision history of the document.options.revs_info?: boolean
- Include a list of revisions of the document, and their availability.options.conflicts?: boolean
- If specified, conflicting leaf revisions will be attached in_conflicts
array.options.attachments?: boolean
- Include attachment data.options.binary?: boolean
- Only evaluated whenattachments
istrue
. Return attachment data as Blobs/Buffers, instead of as base64-encoded strings.options.latest?: boolean
- Forces retrieving latest "leaf" revision, no matter what rev was requested.options.db?: string
- Selects the database to be used. The database is selected by it's name/key. The special key"_default"
selects the default database. Defaults to"_default"
.
initialValue?: Object | function
- Optional initial value ofdoc
result. Has the same behavior asuseState
's initialValue. If used then theoptions
object must be set.
Result
useDoc
results an object with those fields:
doc: PouchDB.Core.Document | null
- The requested document. If there is an error, or its still loading the doc isnull
or theinitialValue
.state: 'loading' | 'done' | 'error'
- Current state of the hook.loading
- It is loading the document. Or it is loading the updated version of it.done
- The document was loaded, and no update is being loaded.error
- There was an error with fetching the document. Look into theerror
field.
loading: boolean
- It is loading. The state isloading
. This is only a shorthand.error: PouchDB.Error | null
- If there was an error, then this field will contain the error. The error is reset tonull
once a document was successfully loaded.
Example Usage
useDoc
is for the use case of reading one document.
Getting a document
import React from "react";
import ReactMarkdown from "react-markdown";
import { useDoc } from "use-pouchdb";
import { ErrorMessage } from "./ErrorMessage";
export function PostViewer({ id }) {
const { doc, loading, state, error } = useDoc(id);
if (state === "error") {
return <ErrorMessage error={error} />;
}
if (loading && doc == null) {
return (
<article>
<hgroup>
<h1>loading ...</h1>
</hgroup>
</article>
);
}
return (
<article>
<hgroup>
<h1>{doc.title}</h1>
<h2>by {doc.author}</h2>
</hgroup>
<ReactMarkdown source={doc.text} />
</article>
);
}
Options
import React from "react";
import ReactMarkdown from "react-markdown";
import { useDoc } from "use-pouchdb";
import { ErrorMessage } from "./ErrorMessage";
import { DocRenderer } from "./DocRenderer";
export function ConflictResolver({ id }) {
const { doc: winning, loading: winningIsLoading } = useDoc(id, {
conflicts: true,
});
const { doc: loosing, loading: loosingIsLoading } = useDoc(id, {
rev: winning._conflict.length > 0 ? winning._conflict[0] : undefined,
});
if (winningIsLoading || loosingIsLoading) {
return <div>loading ...</div>;
}
if (winning._rev === loosing._rev) {
return <div>No conflict!</div>;
}
return (
<div>
<DocRenderer doc={winning} />
<DocRenderer doc={loosing} />
</div>
);
}
With initial value
If the initialValue
is set, then the options
must also be set (it can be an object
or null
).
import React from "react";
import ReactMarkdown from "react-markdown";
import { useDoc } from "use-pouchdb";
import { ErrorMessage } from "./ErrorMessage";
export function PostViewer({ id }) {
const { doc, state, error } = useDoc(id, null, () => ({
_id: id,
title: "...",
author: "...",
text: "loading ...",
}));
if (state === "error") {
return <ErrorMessage error={error} />;
}
return (
<article>
<hgroup>
<h1>{doc.title}</h1>
<h2>by {doc.author}</h2>
</hgroup>
<ReactMarkdown source={doc.text} />
</article>
);
}
The initialValue
can also be used for a blue print of documents. If no doc was fount, use the
initial value and edit it. Once it is saved/created, useDoc
will fetch the newly saved doc.
Select a database
import React from "react";
import ReactMarkdown from "react-markdown";
import { useDoc } from "use-pouchdb";
import { ErrorMessage } from "./ErrorMessage";
export function PostViewer({ id, isLocalReady }) {
const { doc, loading, state, error } = useDoc(id, {
db: isLocalReady ? "local" : "remote",
});
if (state === "error") {
return <ErrorMessage error={error} />;
}
if (loading && doc == null) {
return (
<article>
<hgroup>
<h1>loading ...</h1>
</hgroup>
</article>
);
}
return (
<article>
<hgroup>
<h1>{doc.title}</h1>
<h2>by {doc.author}</h2>
</hgroup>
<ReactMarkdown source={doc.text} />
</article>
);
}