Skip to main content

React Overview

WIP

The React bindings for the upload engine — provider and hooks.

The React layer is deliberately thin: a context provider and a few hooks that read the store through its public interface. All upload logic stays in the core engine, so the binding is just useSyncExternalStore plumbing plus convenience selectors.

Import everything from @gentleduck/upload/react.

Exports

ExportKindPurpose
UploadProvidercomponentPuts a store on React context
useUploaderhookReactive items + grouped selectors + dispatch/on/off
useUploaderActionshookdispatch/on + the raw store, without subscribing to state
useDropzonehookHeadless drag-and-drop + file-picker prop getters
createUploadFactoryhelperA useUploader pre-bound to a specific store
useUploadStorehookThe raw store from context
isUploadStoreguardRuntime check that a value is a store

Provider

Wrap your tree once so descendants can reach the store:

import { UploadProvider } from '@gentleduck/upload/react'
import { store } from './upload'

<UploadProvider store={store}>
  <App />
</UploadProvider>

Reading state

useUploader subscribes to the store and returns the items plus ready-made phase buckets:

const { items, uploading, completed, failed, dispatch, on } =
  useUploader<Intents, Cursors, Purpose, Result>()

Pass your four type parameters (or use createUploadFactory) so items, event payloads, and dispatch are fully typed.

Typical flow

  1. Render lists/progress from useUploader.
  2. Add files with dispatch({ type: 'addFiles', ... }).
  3. React to results with on('upload.completed', ...).
const { items, dispatch, on } = useUploader<Intents, Cursors, Purpose, Result>()

React.useEffect(() => on('upload.completed', ({ localId, result }) => {
  console.log(localId, result)
}), [on])

Adding files

useDropzone gives you drag-and-drop and the native file picker without any markup — spread its prop getters onto your own elements:

const { getRootProps, getInputProps, isDragging } = useDropzone({ purpose: 'attachment' })

<div {...getRootProps()} data-active={isDragging}>
  <input {...getInputProps()} />
</div>

Next