React hooks

Live job status for your UI. The hooks are a thin layer over queue.subscribe() using useSyncExternalStore, so they are tear-free and re-render only when jobs change.

Import from the separate entry point, so the core stays free of React: import { ... } from "@nijatk/react-native-queuekit/react". React 18 or newer is required.

QueueProvider

The provider only makes the queue available to hooks. It does not start or stop it: the queue starts when created (unless autoStart: false).

Hooks

Hook	Returns
`useQueue()`	The queue. Throws outside a provider: `useQueue must be used inside <QueueProvider>`.
`useJobs(filter?)`	Live array of jobs, oldest first. Filter by `status` and/or `type`.
`useJob(id)`	One job, or `undefined` once it completes or is removed.
`useQueueStats()`	`{ pending, active, failed, total }`

useQueue

useJobs

The filter's fields are compared by value, so passing a fresh object literal on each render is fine and does not cause extra work.

useJob

"No job" means done, or removed

A finished job is deleted, so useJob cannot tell success from "never existed". If you must tell them apart, remember the id when you enqueue, as above, or listen for the completed event.

useQueueStats

Ready-made components

Sync banner

Upload list with progress, retry and cancel

Tab badge

Show pending items inline (optimistic list)

Writing your own hooks

Run code on queue events

Is anything of this type in flight?

Without the provider

Hooks need the provider only to find the queue. In a module that already imports it, use useSyncExternalStore directly:

Performance notes

Components re-render on any job change. Scope hooks narrowly: a list screen uses useJobs({ type }), a badge uses useQueueStats().
Progress updates write to storage and notify subscribers on every progress() call. Throttle in the handler if your source reports hundreds of events per second: report every 1% or every 250 ms.
useJob(id) scans the job list. It is perfect for individual rows, but for thousands of jobs prefer one useJobs at the list level and pass jobs down.
Use React.memo for rows keyed by job.id. A job object is replaced when it changes, so unchanged rows keep their reference.

Testing components

Create a queue with memoryStorage() and autoStart: false, enqueue jobs, and render inside a provider. Wrap queue changes in act().