API reference › @evolu/react › ReactBinding
Defined in: local‑first/createEvoluBinding.ts:44
Properties
EvoluAppProvider
readonly EvoluAppProvider: FC<{
children: ReactNode;
value: Promise<EvoluApp<S, D>>;
withoutAppOwner: ReactNode;
}>;
Defined in: local‑first/createEvoluBinding.ts:157
Provides an EvoluApp to React descendants. Its children get the
instance of the AppOwner this tab has open through EvoluContext, so
useEvolu and the query hooks read that AppOwner's data, and
useEvolu().appOwner is that AppOwner. They remount when the tab opens
another AppOwner, or the AppOwner again after a removal and restore or its
database's deletion. While the tab has no AppOwner open, such as on a
device without one or after a removal of the open one, it renders
withoutAppOwner, such as a choice to open one of useAppOwners, create
one, or restore one. It suspends while the app or the AppOwner's instance
opens, so put it under a Suspense boundary, and pass the same promise on
every render, such as one created at module scope. The queries of a refused
database stay suspended, so put the children that read queries under a
Suspense boundary of their own, and render evoluError and the account UI,
which useEvoluApp and useAppOwners give to open or remove an AppOwner,
outside it, where they stay usable.
EvoluContext
readonly EvoluContext: FC<{
children?: ReactNode;
value: AppOwnerEvolu<S>;
}>;
Defined in: local‑first/createEvoluBinding.ts:55
Provides Evolu to React descendants consumed via useEvolu. An app
of createEvolu renders it with its instance, such as <EvoluContext value={use(evoluPromise)}> under a Suspense boundary, with the promise
created once at module scope. An app of createEvoluApp renders
EvoluAppProvider, which provides it.
useAppOwners
readonly useAppOwners: () => readonly AppOwnerEntry[];
Defined in: local‑first/createEvoluBinding.ts:170
Returns EvoluApp.appOwners, the AppOwners the app can open on this device, and re-renders when they change.
useDeviceEvolu
readonly useDeviceEvolu: () => DeviceEvolu<D>;
Defined in: local‑first/createEvoluBinding.ts:176
Returns EvoluApp.device, the instance of the device database with the app's own device tables.
useDeviceQueries
readonly useDeviceQueries: <Q, OQ>(queries: [...Q[]], options?: UseQueriesOptions<OQ>) => [...QueriesToQueryRows<Q>[], ...QueriesToQueryRows<OQ>[]];
Defined in: local‑first/createEvoluBinding.ts:185
The same as useQueries, for queries of the app's device tables.
useDeviceQuery
readonly useDeviceQuery: <R>(query: Query<D, R>, options?: UseQueryOptions) => QueryRows<R>;
Defined in: local‑first/createEvoluBinding.ts:179
The same as useQuery, for a query of the app's device tables.
useEvolu
readonly useEvolu: () => AppOwnerEvolu<S>;
Defined in: local‑first/createEvoluBinding.ts:61
Returns the current Evolu instance from EvoluContext, without
disposal, because the component doesn't own it.
useEvoluApp
readonly useEvoluApp: () => EvoluApp<S, D>;
Defined in: local‑first/createEvoluBinding.ts:164
Returns the EvoluApp from EvoluAppProvider.
useOwner
readonly useOwner: (owner:
| ReadonlyOwner
| Owner
| null, transports?: readonly [OwnerWebSocketTransport, OwnerWebSocketTransport]) => void;
Defined in: local‑first/createEvoluBinding.ts:116
Uses an Owner for sync through Evolu.useOwner while the component is mounted, and stops when it unmounts or the Evolu instance, owner, or transports change. A null owner uses none, for a component that waits for one. Evolu.deleteOwner of the owner ends its use, and the component uses the owner again only once it remounts or the Evolu instance, owner, or transports change.
The owner and transports are compared by content, so recreating them on each render keeps the same registration.
useOwnerSyncStatus
readonly useOwnerSyncStatus: {
(syncState: ReadonlyStore<
| SyncState
| null>): OwnerSyncStatus;
(syncState: ReadonlyStore<
| SyncState
| null>, owner:
| ReadonlyOwner
| Owner
| null): OwnerSyncStatus;
};
Defined in: local‑first/createEvoluBinding.ts:132
Returns the OwnerSyncStatus of an owner in the database of the
Evolu instance from EvoluContext, and re-renders when it changes,
not with every snapshot. Without an owner, it is the status of
Evolu.appOwner. Otherwise pass the owner useOwner takes; a null
owner, for a component that waits for one, gives NoRelays. Pass the
SyncStateDep.syncState
store of the deps the instance was created with, because the context holds
only the instance. Before the first snapshot and during server rendering,
it returns NoRelays. See OwnerSyncStatus for what to show.
Call Signature
(syncState: ReadonlyStore<
| SyncState
| null>): OwnerSyncStatus;
Call Signature
(syncState: ReadonlyStore<
| SyncState
| null>, owner:
| ReadonlyOwner
| Owner
| null): OwnerSyncStatus;
useQueries
readonly useQueries: <Q, OQ>(queries: [...Q[]], options?: UseQueriesOptions<OQ>) => [...QueriesToQueryRows<Q>[], ...QueriesToQueryRows<OQ>[]];
Defined in: local‑first/createEvoluBinding.ts:88
The same as useQuery, but for many queries.
The number of queries must remain stable across renders.
useQuery
readonly useQuery: <R>(query: Query<S, R>, options?: UseQueryOptions) => QueryRows<R>;
Defined in: local‑first/createEvoluBinding.ts:78
Load and subscribe to the Query, and return an object with rows and row
properties that are automatically updated when data changes.
Note that useQuery uses React Suspense. It means every usage of
useQuery blocks rendering until loading is completed. To avoid loading
waterfall with more queries, use useQueries. A query SQLite fails throws
its error to the nearest error boundary; see Evolu.loadQuery.
Resetting the boundary throws the cached error again until a mutation or
sync invalidates it.
To start loading before rendering, which is rarely needed as local queries
are typically fast, call Evolu.loadQuery. useQuery then reuses
that load unless a mutation or sync drops it first.
useQuerySubscription
readonly useQuerySubscription: <R>(query: Query<S, R>, options?: Partial<{
once: boolean;
}>) => QueryRows<R>;
Defined in: local‑first/createEvoluBinding.ts:94