# @uploadcn/core (/docs/reference/core)



<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @uploadcn/core
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Entry points: `@uploadcn/core` (engine, adapters, validation, utilities),
`@uploadcn/core/image` (image processing), `@uploadcn/core/tus` (tus adapter, needs
`tus-js-client`).

## createUploader [#createuploader]

```ts
function createUploader<TResult>(options: UploaderOptions<TResult>): Uploader<TResult>
```

### UploaderOptions [#uploaderoptions]

<TypeTable
  type="{
  adapter: { type: &#x22;UploadAdapter<TResult>&#x22;, required: true },
  autoUpload: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Queue files as soon as they're added.&#x22; },
  concurrency: { type: &#x22;number&#x22;, default: &#x22;3&#x22;, description: &#x22;Simultaneous uploads.&#x22; },
  retry: { type: &#x22;RetryOptions | false&#x22;, default: &#x22;{ retries: 3, baseDelay: 1000, maxDelay: 30000, factor: 2, jitter: true }&#x22; },
  duplicates: { type: '&#x22;reject&#x22; | &#x22;replace&#x22; | &#x22;allow&#x22;', default: '&#x22;reject&#x22;', description: &#x22;Same name, size, type and modification time.&#x22; },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  minSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  minFiles: { type: &#x22;number&#x22;, description: &#x22;Checked with validateFileCount.&#x22; },
  image: { type: &#x22;{ minWidth?, minHeight?, maxWidth?, maxHeight? }&#x22; },
  media: { type: &#x22;{ minDuration?, maxDuration? }&#x22;, description: &#x22;Seconds.&#x22; },
  validate: { type: &#x22;FileValidator | FileValidator[]&#x22; },
  transform: { type: &#x22;(file, { signal }) => File | Blob | Promise<File | Blob>&#x22; },
  process: { type: &#x22;(item, { signal, result, setStatus, setMeta }) => Promise<TResult | void>&#x22;, description: &#x22;Server-side work after upload: processing, scanning, ingestion.&#x22; },
  persistence: { type: &#x22;UploadPersistence&#x22;, description: &#x22;e.g. createIndexedDBPersistence().&#x22; },
  network: { type: &#x22;NetworkMonitor | false&#x22;, description: &#x22;Defaults to navigator.onLine in browsers.&#x22; },
  progressInterval: { type: &#x22;number&#x22;, default: &#x22;100&#x22;, description: &#x22;Minimum ms between progress updates.&#x22; },
}"
/>

### Uploader [#uploader]

| Method                                            | Description                                                   |
| ------------------------------------------------- | ------------------------------------------------------------- |
| `add(files, { meta?, start? })`                   | Validate, transform and enqueue. Resolves with the new items. |
| `start(selector?)`                                | Queue idle items.                                             |
| `pause(selector?)` / `resume(selector?)`          | Pause queued or resumable uploads.                            |
| `cancel(selector?)`                               | Abort and clean up server state.                              |
| `retry(selector?)`                                | Retry failed or cancelled items (resets attempts).            |
| `remove(selector?)` / `clearCompleted()`          | Remove items.                                                 |
| `update(id, { status?, result?, error?, meta? })` | Drive processing/scanning states from outside.                |
| `getState()` / `subscribe(listener)`              | Immutable snapshot + change listener.                         |
| `on(event, handler)`                              | Typed events; returns an unsubscribe function.                |
| `getItem(id)` / `canPause(item)`                  | Helpers.                                                      |
| `restore()`                                       | Load persisted uploads (paused).                              |
| `setOptions(partial)` / `getOptions()`            | Update options at runtime.                                    |
| `mount()`                                         | Attach network listeners; returns a cleanup.                  |
| `destroy()`                                       | Abort everything and release resources.                       |

A `selector` is an id, an array of ids, a predicate, or nothing (all items).

## UploadItem [#uploaditem]

<TypeTable
  type="{
  id: { type: &#x22;string&#x22; },
  batchId: { type: &#x22;string&#x22;, description: &#x22;Shared by files added together.&#x22; },
  file: { type: &#x22;File&#x22;, description: &#x22;After transforms.&#x22; },
  originalFile: { type: &#x22;File&#x22;, description: &#x22;As selected.&#x22; },
  &#x22;name / size / type&#x22;: { type: &#x22;string / number / string&#x22; },
  status: { type: &#x22;UploadStatus&#x22; },
  progress: { type: &#x22;{ loaded, total, percent, speed, eta }&#x22; },
  chunks: { type: &#x22;{ completed, total } | null&#x22; },
  error: { type: &#x22;UploadError | null&#x22; },
  issues: { type: &#x22;ValidationIssue[]&#x22;, description: &#x22;Why a file was rejected.&#x22; },
  attempts: { type: &#x22;number&#x22; },
  retryAt: { type: &#x22;number | null&#x22;, description: &#x22;When the next automatic retry happens.&#x22; },
  pauseReason: { type: '&#x22;user&#x22; | &#x22;offline&#x22; | &#x22;restored&#x22; | null' },
  result: { type: &#x22;TResult | undefined&#x22; },
  meta: { type: &#x22;Record<string, unknown>&#x22; },
  resumeState: { type: &#x22;unknown&#x22;, description: &#x22;Adapter-owned, JSON-serializable.&#x22; },
  restored: { type: &#x22;boolean&#x22; },
  &#x22;createdAt / startedAt / completedAt&#x22;: { type: &#x22;number | null&#x22; },
}"
/>

## UploadError [#uploaderror]

```ts
new UploadError(message, { code, retryable?, status?, retryAfter?, details?, cause? })
```

`code`: `network`, `timeout`, `http`, `aborted`, `offline`, `validation`, `rejected`, `unknown`.
Helpers: `isUploadError`, `toUploadError`, `httpError`, `isRetryableStatus`, `parseRetryAfter`.

## Validation [#validation]

`validateFile`, `validateFiles`, `validateFileSync`, `validateFileCount`, `matchesAccept`,
`parseAccept`, `toAcceptAttribute`, `getFileType`.

## Adapters [#adapters]

`s3Adapter`, `r2Adapter`, `presignedAdapter`, `multipartAdapter`, `httpAdapter`,
`routeAdapter`, `mockAdapter`, and `tusAdapter` from `@uploadcn/core/tus`. The default
transport is `xhrTransport` (XMLHttpRequest, for upload progress).

## Persistence & capabilities [#persistence--capabilities]

`createIndexedDBPersistence({ name?, store?, maxAge? })`, `createMemoryPersistence()`,
`getBackgroundCapabilities()`, `requestPersistentStorage()`.

## OCR [#ocr]

`ocrEndpoint(url, options?)` sends files to your OCR route; `tesseractOcr({ load, lang? })`
reads them in the browser; `ocrProcess(recognize, { required?, filter? })` turns either into
an uploader `process` step that stores the result on `item.meta.ocr`. All return or use
`OcrResult`: `{ text, pages, confidence?, fields?, markdown?, provider }`. See
[OCR](/docs/guides/ocr).

## Image (`@uploadcn/core/image`) [#image-uploadcncoreimage]

`transformImage(file, options)`, `compressImage(file, options)`, `imageTransform(options)`,
`getImageDimensions(file)`, `getRotatedSize`, `getFitScale`, `canTransformImage`.

## Utilities [#utilities]

`formatBytes`, `formatSpeed`, `formatDuration`, `getUploadSummary`, `getPartSize`,
`createChunks`, `withRetry`, `getRetryDelay`, `sleep`, `getDroppedFiles`,
`getClipboardFiles`, `isFileDrag`, `getMediaDuration`, `KiB`, `MiB`, `GiB`.