React hooks for integrating with RxDB
Click to expand
Nothing fancy, just conveniently handles common use cases such as:
- subscribing to query observables and translating results into React state
- cleaning up after subscriptions where necessary
- paginating results
- maintaining useful state information (i.e. data fetching or data exhaustion during pagination)
- lazily creating or destroying collections
# using npm
npm install rxdb-hooks
# using yarn
yarn add rxdb-hooksRoot.jsx:
import React, { useEffect } from 'react';
import { Provider } from 'rxdb-hooks';
import initialize from './initialize';
const Root = () => {
const [db, setDb] = useState();
useEffect(() => {
// RxDB instantiation can be asynchronous
initialize().then(setDb);
}, []);
// Until db becomes available, consumer hooks that
// depend on it will still work, absorbing the delay
// by setting their state to isFetching:true
return (
<Provider db={db}>
<App />
</Provider>
);
};Consumer.jsx:
import React from 'react';
import { useRxData } from 'rxdb-hooks';
const Consumer = () => {
const { result: characters, isFetching } = useRxData(
// the collection to be queried
'characters',
// a function returning the query to be applied
collection =>
collection.find({
selector: {
affiliation: 'jedi',
},
})
);
if (isFetching) {
return 'loading characters...';
}
return (
<ul>
{characters.map((character, idx) => (
<li key={idx}>{character.name}</li>
))}
</ul>
);
};initialize.js:
const initialize = async () => {
// create RxDB
const db = await createRxDatabase({
name: 'test_database',
});
// create a collection
const collection = await db.addCollections({
characters: {
schema: {
title: 'characters',
version: 0,
type: 'object',
primaryKey: 'id',
properties: {
id: {
type: 'string',
maxLength: 100,
},
name: {
type: 'string',
},
},
},
},
});
// maybe sync collection to a remote
// ...
return db;
};The core API of rxdb-hooks remains largely the same across all major versions beyond 1.x, however some parts of the internal
implementation (most notably the plugin) differ based on the version of rxdb we need to target *.
Please use the appropriate version of rxdb-hooks as per this table:
| rxdb-hooks version | targeted RxDB version |
|---|---|
5.x |
14.x |
4.1.x |
13.x |
4.0.x |
10.x, 11.x, 12.x |
3.x |
9.x |
1.x, 2.x |
8.x |
* Versions 7.x of RxDB and below have not been tested and are not guaranteed to work with rxdb-hooks
useRxDocumenthas been dropped; for fetching single documents simply useuseRxQueryoruseRxData- observing lazily created collection has become an opt-in feature that, if needed, has to be explicitly enabled by using the provided plugin. For more info see Lazy instantiation of RxDatabase & RxCollections
The <Provider /> makes the RxDatabase instance available to nested components and is required for all subsequent hooks to work.
| Property | Type | Description |
|---|---|---|
db |
RxDatabase |
the RxDatabase instance to consume data from |
Returns the RxDatabase instance made available by the <Provider />
function useRxDB(): RxDatabaseconst db = useRxDB();Given a collection name returns an RxCollection instance, if found in RxDatabase.
function useRxCollection<T>(name: string): RxCollection<T> | nullconst collection = useRxCollection('characters');Subscribes to given RxQuery object providing query results and some helpful extra state variables.
function useRxQuery<T>(query: RxQuery, options?: UseRxQueryOptions): RxQueryResult<T>| Option | Type | Description |
|---|---|---|
pageSize |
number |
(optional) enables pagination & defines page limit |
pagination |
"Traditional" | "Infinite" |
(optional) determines pagination mode: Traditional: results are split into pages, starts by rendering the first page and total pageCount is returned, allowing for requesting results of any specific page. Infinite: first page of results is rendered, allowing for gradually requesting more. Default: "Traditional" |
json |
boolean |
(optional) when true resulting documents will be converted to plain JavaScript objects; equivalent to manually calling .toJSON() on each RxDocument. Default: false |
| Property | Type | Description |
|---|---|---|
result |
T[] | RxDocument<T>[] |
the resulting array of objects or RxDocument instances, depending on json option |
isFetching |
boolean |
fetching state indicator |
currentPage |
number |
relevant in all pagination modes; holds number of current page |
isExhausted |
boolean |
relevant in Infinite pagination; flags result list as "exhausted", meaning all documents have been already fetched |
fetchMore |
() => void |
relevant in Infinite pagination; a function to be called by the consumer to request documents of the next page |
resetList |
() => void |
relevant in Infinite pagination; a function to be called by the consumer to reset paginated results |
pageCount |
number |
relevant in Traditional pagination; holds the total number of pages available |
fetchPage |
(page: number) => void |
relevant in Traditional pagination; a function to be called by the consumer to request results of a specific page |
const collection = useRxCollection('characters');
const query = collection.find().where('affiliation').equals('Jedi');
const { result } = useRxQuery(query);const collection = useRxCollection('characters');
const query = collection.find().where('affiliation').equals('Jedi');
const {
result: characters,
isFetching,
fetchMore,
isExhausted,
} = useRxQuery(query, {
pageSize: 5,
pagination: 'Infinite',
});
if (isFetching) {
return 'Loading...';
}
return (
<CharacterList>
{characters.map((character, index) => (
<Character character={character} key={index} />
))}
{!isExhausted && <button onClick={fetchMore}>load more</button>}
</CharacterList>
);const collection = useRxCollection('characters');
const query = collection.find({
selector: {
affiliation: 'Jedi',
},
});
const {
result: characters,
isFetching,
fetchPage,
pageCount,
} = useRxQuery(query, {
pageSize: 5,
pagination: 'Traditional',
});
if (isFetching) {
return 'Loading...';
}
// render results and leverage pageCount to render page navigation
return (
<div>
<CharacterList>
{characters.map((character, index) => (
<Character character={character} key={index} />
))}
</CharacterList>
<div>
{Array(pageCount)
.fill()
.map((x, i) => (
<button
onClick={() => {
fetchPage(i + 1);
}}
>
page {i + 1}
</button>
))}
</div>
</div>
);Convenience wrapper around useRxQuery that expects a collection name & a query constructor function
function useRxData<T>(
collectionName: string,
queryConstructor: ((collection: RxCollection<T>) => RxQuery<T> | undefined) | undefined,
options?: UseRxQueryOptions
): RxQueryResult<T>const { result } = useRxData('characters', collection =>
collection.find().where('affiliation').equals('Jedi')
);By design, useRxQuery will re-subscribe to query object whenever it changes, allowing
for query criteria to be modified during component updates. For this reason, to
avoid unnecessary re-subscriptions, query should be memoized (i.e. via react's useMemo):
const { affiliation } = props;
const collection = useRxCollection('characters');
const query = useMemo(
() =>
collection.find({
selector: {
affiliation,
},
}),
[collection, affiliation]
);
const { result } = useRxQuery(query);Same goes for useRxData and the queryConstructor function:
const { affiliation } = props;
const queryConstructor = useCallback(
collection =>
collection.find({
selector: {
affiliation,
},
}),
[affiliation]
);
const { result } = useRxData('characters', queryConstructor);All rxdb-hooks give you the ability to lazily instantiate the database and the
collections within it. Initial delay until the above become available is absorbed
by indicating the state as fetching (isFetching:true).
Since v5.0.0 of rxdb-hooks, observing newly created collections has become
an opt-in feature that, if needed, has to be enabled via the provided observeNewCollections plugin:
import { addRxPlugin } from 'rxdb';
import { observeNewCollections } from 'rxdb-hooks';
addRxPlugin(observeNewCollections);Adding the plugin makes it possible for all rxdb-hooks to pick up data from collections that are lazily added after the inital db initialization.
Also note that lazily instantiating the rxdb instance itself is supported out-of-the-box, the plugin only affects lazy collection creation.
Performing mutations on data is possible through the APIs provided by RxDocument and RxCollection:
const collection = useRxCollection('characters');
collection.upsert({
name: 'Luke Skywalker',
affiliation: 'Jedi',
});MIT
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent