@uploader/react

React picker and headless upload client for the Uploader platform.

Installation

npm install @uploader/react

Quick start — React picker

import { PickerOverlay } from '@uploader/react'
import '@uploader/react/styles.css'

function App() {
  return (
    <PickerOverlay
      apiKey="pk_your_api_key"
      apiUrl="https://your-api.example.com"
      onUploadDone={(res) => console.log(res.filesUploaded)}
    />
  )
}

Headless client (no React required)

import { UploaderClient } from '@uploader/react/core'

const client = new UploaderClient({
  apiKey: 'pk_your_api_key',
  apiUrl: 'https://your-api.example.com',
})

const result = await client.upload(file, { filename: 'photo.jpg' })
console.log(result.handle)   // e.g. "abc123def456"
console.log(result.url)      // public delivery URL

Large files (≥ 6 MiB) are automatically uploaded via multipart; smaller files use a single PUT.

Components

<PickerOverlay>

Full-screen modal picker with drag-and-drop, progress, and error UI.

| Prop | Type | Description | |---|---|---| | apiKey | string | API key (pk_…) | | apiUrl | string | Base URL of the API server | | onUploadDone | (res: PickerResponse) => void | Called when all uploads complete | | accept | string | MIME type filter (e.g. image/*) | | maxFiles | number | Maximum number of files selectable at once |

<DropPane>

Inline drop zone that can be embedded in a form.

usePicker(options)

Headless hook — returns { open, uploading, files, errors }.

Camera capture

Both <PickerOverlay> and <DropPane> can capture a photo straight from the device camera. A Take photo button appears next to Browse files whenever the browser supports getUserMedia and the picker accepts images. The capture flows through the exact same pipeline as a dropped or browsed file — it lands in the queue with a preview, can be cropped/rotated in the in-picker editor, and is then uploaded normally.

<PickerOverlay
  apikey="pk_…"
  open={open}
  onClose={() => setOpen(false)}
  pickerOptions={{
    accept: ['image/*'],
    // Sources offered to the user. Omit to offer everything supported.
    fromSources: ['local_file_system', 'camera'],
    // 'user' = front/selfie (mirrored, default) · 'environment' = rear camera
    cameraFacingMode: 'environment',
  }}
/>

Notes:

• The camera requires a secure context (HTTPS or localhost) and user permission. Permission/no-camera errors are surfaced inline with a retry.
• Pass fromSources: ['local_file_system'] to hide the camera even where it is supported; omit fromSources to offer it by default.
• The <CameraCapture> component and the isCameraSupported() / shouldOfferCamera() helpers are exported for fully custom pickers.

Signed policies

When the account has requireSigned enabled, pass a signed policy on upload:

const result = await client.upload(file, {
  policy: 'base64-encoded-policy',
  signature: 'hmac-sha256-hex-signature',
})

Build signed policies via the admin dashboard (/api-keys → "Build signed policy") or directly via POST /api/admin/api-keys/:id/sign.

Building

npm run build   # outputs to dist/ (ESM + CJS + types)