@alsocoder/apna-upload

@alsocoder/apna-upload

Provider-free React file upload component with drag-and-drop, progress, cancel, retry, and validation.

Install

npm install @alsocoder/apna-upload

Peer dependencies: react, react-dom.

Optional: pdfjs-dist for PDF first-page thumbnails (enablePdfPreview).

Setup

import "@alsocoder/apna-upload/styles.css"

Basic usage

import { ApnaUpload } from "@alsocoder/apna-upload"

async function uploadFile(file: File, { signal, onProgress }) {
  const body = new FormData()
  body.append("file", file)

  const response = await fetch("/api/upload", {
    method: "POST",
    body,
    signal,
  })

  if (!response.ok) {
    throw new Error("Upload failed")
  }

  onProgress(100)
  return response.json()
}

export function ResumeField() {
  const [resume, setResume] = useState("")

  return (
    <ApnaUpload
      label="Resume"
      accept=".pdf"
      upload={uploadFile}
      transformResult={(result) => result.file.path}
      value={resume}
      onChange={setResume}
    />
  )
}

Multiple files

<ApnaUpload
  multiple
  maxFiles={5}
  accept="image/*"
  upload={uploadFile}
  value={images}
  onChange={setImages}
/>

Result modes

resultMode	onChange value
"url" (default)	string or string[] (via transformResult)
"file"	File or File[]

Hooks and callbacks

Prop	Purpose
beforeUpload	Transform or reject a file before upload (null = reject). Use for crop, compression, watermark, EXIF fix.
transformResult	Map API response to field value. Default extracts { url } or a string.
onUploading	Called during upload with (file, progress) — use for analytics or custom progress UI
onUploaded	Called per file after successful upload
onRemoved	Called when user removes a completed file
onError	Per-file error callback (wire your own toast)

Validation

Built-in rules: accept, maxSize, maxFiles.

For custom rules, use validate:

<ApnaUpload
  accept="image/*"
  validate={(file) => {
    if (!file.name.endsWith(".png")) {
      return "Only PNG allowed"
    }
    return true
  }}
  upload={uploadFile}
/>

Return true to allow, or a string error message to reject. Supports async validators.

Disabled and read-only

Prop	Behavior
disabled	No browse, drop, paste, cancel, retry, or remove
readOnly	Files visible but no interactions (same as disabled for actions)

<ApnaUpload disabled upload={uploadFile} />
<ApnaUpload readOnly value={url} upload={uploadFile} />

Custom preview

Override the default thumbnail with renderPreview:

<ApnaUpload
  renderPreview={(file, item) => (
    <div className="my-card">
      <strong>{file.name}</strong>
      <span>{item.progress}%</span>
    </div>
  )}
  upload={uploadFile}
/>

Headless hook

Use useApnaUpload() for custom UI — same engine as the component:

import { useApnaUpload } from "@alsocoder/apna-upload"

const { items, enqueueFiles, cancelItem, retryItem, removeItem } = useApnaUpload({
  upload: uploadFile,
  validate: (file) => file.size < 5_000_000 || "Max 5 MB",
  onUploading: (file, progress) => track("upload", { file: file.name, progress }),
})

Architecture

ApnaUpload (UI)
├── Upload Engine   — queue, progress, cancel, retry
├── Validation      — accept, maxSize, maxFiles, validate()
├── Preview         — image/PDF thumbnails, renderPreview
├── Drag & Drop     — dropzone
├── Paste           — clipboard files
├── Reorder         — drag sort (multiple)
└── UI              — dropzone + file list

useApnaUpload() exposes the engine layer without UI.

Features

Feature	Status
Drag & drop	Yes
Browse	Yes
Multiple	Yes
Preview (image)	Yes
PDF preview	Yes (enablePdfPreview + optional pdfjs-dist)
Progress	Yes
Retry	Yes
Cancel	Yes
beforeUpload	Yes
onUploading	Yes
validate (custom)	Yes
renderPreview	Yes
disabled / readOnly	Yes
onUploaded / onRemoved	Yes
useApnaUpload() hook	Yes
Max files / max size / accept	Yes
resultMode url | file	Yes
AbortController	Yes
Paste upload (Ctrl+V)	Yes (enablePaste, default on)
Reorder (drag)	Yes (enableReorder + multiple)
Chunk upload	Adapter contract — see below

Chunk upload (adapter contract)

For large files, your upload function may receive optional chunk metadata:

type ApnaUploadFn = (
  file: File,
  ctx: {
    signal: AbortSignal
    onProgress: (percent: number) => void
    chunk?: { index: number; total: number; slice: Blob }
  }
) => Promise<unknown>

Implement multipart/resumable logic in your adapter — the component does not ship S3/Cloudinary adapters.

Custom upload adapters

Implement any backend in the upload function:

• S3 presigned URL
• Cloudinary unsigned upload
• Firebase Storage
• Supabase storage
• Your REST API

Return any JSON shape and use transformResult to map it to your form value.

License

MIT