Skip to main content

React hooks

import { useCloudItem } from 'react-native-cloud-sync/hooks'

A separate entry point, so code outside React (sagas, background tasks) doesn't import it. The hooks handle the two usual bugs: a stale response overwriting a newer one, and setState after unmount.

useCloudItem​

Binds one key to component state.

import { useCloudItem } from 'react-native-cloud-sync/hooks'

function SettingsScreen () {
const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')

if (loading) return <Spinner />
if (error != null) return <SyncError code={error.code} />

return <SettingsForm value={value} onChange={setValue} />
}
valueParsed value, or null when the key does not exist
loadingTrue until the first read settles, and during refresh()
errorLast read or write failure; cleared by the next success
setValueWrites through, updating local state first
removeDeletes the key
refreshRe-reads

Values go through JSON.parse/JSON.stringify by default. For a plain string, pass identity functions:

useCloudItem<string>(store, 'theme', {
parse: raw => raw,
serialize: value => value,
})

It re-reads when another device writes​

watch (default true) subscribes to onRemoteChange, so another device's edit shows up without a refresh. An event with an empty keys list (account or quota change) also triggers a re-read.

Writes are optimistic and do not revert​

setValue updates local state immediately and keeps it on failure, since the outbox usually delivers anyway. A failed read keeps the last known value.

Stale responses cannot land​

A read whose result is stale (key changed, overtaken, invalidated) is dropped instead of written into state. When key changes, value falls back to initialValue while the new key loads, never showing the old key's value.

useCloudItems​

Binds a list of keys with one batched multiGet instead of one useCloudItem per row. With resolve on the store, each key resolves as getItem would, including read repair. See the cost.

function NotesList ({ noteIds }: { noteIds: string[] }) {
const { values, setValue, loading } = useCloudItems<Note>(store, noteIds)

if (loading) return <Spinner />

return noteIds.map(id => (
<NoteRow key={id} note={values[id]} onChange={next => setValue(id, next)} />
))
}
valuesParsed value per key. A key mapped to null was fetched and doesn't exist; a key absent hasn't been fetched yet
loadingTrue only during the initial fetch of keys, and during refresh()
errorLast read or write failure; cleared by the next success
setValue(key, next) => Promise<void> - writes through, updating local state first
remove(key) => Promise<void>
refreshRe-fetches every key currently tracked

It only fetches what it doesn't already know​

Mount, refresh() and a matching remote-change event fetch. A key that merely joins the tracked list (say, useCloudCollection adding one after a local write) is not fetched, so a slow in-flight fetch can't overwrite the local write with a stale answer.

Loading only reflects the initial fetch and refresh()​

Remote events update values in the background without flipping loading, so live updates don't flash a spinner over visible rows.

useCloudCollection​

useCloudItems plus a live list of every key starting with prefix.

function NotesList () {
const { keys, values, setValue, remove } = useCloudCollection<Note>(store, 'note:')

return keys.map(key => (
<NoteRow key={key} note={values[key]} onChange={next => setValue(key, next)} onDelete={() => remove(key)} />
))
}

Returns the useCloudItems result plus keys: string[]. Re-lists on mount and after any remote-change event that could have added or removed a member.

setValue on a new key adds it to keys immediately, and remove drops it immediately. A listing already in flight can't undo either.

useAccountStatus​

import { icloudKV } from 'react-native-cloud-sync'
import { useAccountStatus } from 'react-native-cloud-sync/hooks'

function SyncBanner () {
const { status, identityChanged } = useAccountStatus(icloudKV)

if (status === 'noAccount') return <SignInPrompt />
if (identityChanged) return <SwitchedAccountNotice />
return null
}

status is the provider's AccountStatus, not a boolean, since signed out, temporarily unavailable and undetermined need different UI. cloudKit reports all five values; icloudKV only available or noAccount (why). An account event arriving during a status query wins over the query's older answer.

identityChanged is latched: it stays true once a different identity signs in, so a screen mounting after the event still sees it.

usePendingWrites​

Drives a "pending sync" indicator.

function PendingBadge () {
const { pending, flush, discard } = usePendingWrites(store)

if (pending.length === 0) return null

return (
<Row>
<Text>{pending.length} waiting to sync</Text>
<Button title="Retry now" onPress={flush} />
<Button title="Discard" onPress={() => discard()} />
</Row>
)
}

Polls every 2s by default (cheap: pendingWrites() is a synchronous read). Pass 0 to read only on mount. Each entry has lastErrorCode, so the UI can say why it's stuck.

useRemoteChange​

useRemoteChange(store, ({ keys }) => {
for (const key of keys) queryClient.invalidateQueries([key])
})

The listener is held in a ref, so an inline function doesn't resubscribe every render.

useQuota​

const { quota, loading, refresh } = useQuota(store)

Not polled (each read is a network round trip per provider). Call refresh() when a settings screen opens or after a large write.

Cleaning up​

No hook calls store.dispose(), since a store outlives its components. Call it yourself when done (sign-out, test teardown).