Events

Every upload, file, drag, pipeline, and UI interaction in upup flows through one typed event bus on UpupCore. Each framework's callback props are a convenience layer over that bus, and a lossy one — the bus carries events no prop exposes, and a few props fire on paths that emit no event at all. When in doubt, listen to the event.

Listening

With the visual uploader, use the callback props:

<UpupUploader
    uploadEndpoint="/api/upload-token"
    onUploadStart={() => console.log('started')}
    onFileUploadProgress={(file, p) => console.log(file.name, p.percentage)}
    onUploadComplete={files => console.log(files.map(f => f.key))}
    onError={message => console.error(message)}
/>

Headless, subscribe to the bus directly. on() returns an unsubscribe function:

import { UpupCore } from '@upupjs/core'

const core = new UpupCore({ uploadEndpoint: '/api/upload-token' })

const off = core.on('upload-progress', ({ fileId, loaded, total }) => {
    console.log(fileId, Math.round((loaded / total) * 100))
})

core.on('upload-error', ({ error, file }) => {
    console.error(file?.name ?? 'run', error.message)
})

// Later:
off()
core.destroy()

The React hook useUpupUpload exposes the same on(event, handler), and the uploader ref exposes the underlying core. See Headless Usage for both.

Bare event names are the typed catalog below and nothing else — an unknown bare name is a compile error at the on / emit site.

There is exactly one upload-failure event: upload-error. A bare 'error' event does not exist. Failed resume() calls route through upload-error, and so does every pipeline step failure except HEIC conversion, which downgrades to a pipeline-error diagnostic. Cloud-drive plugins emit namespaced <provider>:<event> names (e.g. google-drive:files-loaded, one-drive:session-expired) which pass through the bus untyped and are not part of this catalog — see Credentials & Cloud Drives.

Events whose payload is listed as {} carry an empty object; the payload argument exists but has no fields.

Upload lifecycle

A run drives one status projection, and the events below are emitted as it moves between states:

One failed file emits upload-error twice. The per-file emission fires first (with file), then the batch rejects and the terminal handler emits a second time (without file, carrying an aggregate UpupUploadBatchError). Anything bound to upload-error — including the onError prop — therefore runs twice for a single failure. Deduplicate on file being present if you only want the per-file signal, and treat the file-less emission as "the run is over".

Vanilla only: @upupjs/vanilla also emits upload-error when a link import fails, so a URL-fetch failure reaches the same channel as an upload failure. React's URL path calls onError without emitting the event. Don't assume upload-error implies a transfer was attempted.

File operations

Plugins and options

Recovery

UI flow

Image editor

React and Preact only — the other frameworks intentionally stub the editor.

Drag, drop, and paste

Pipeline diagnostics

The processing pipeline (hash, HEIC, EXIF, thumbnail, compress) reports through these as it works through each file.

pipeline-error is not the general step-failure event. Only the HEIC step catches its own errors and reports them here, downgrading a failed conversion to a diagnostic while the run continues. Every other step failure propagates out of the pipeline uncaught and fails the whole run through upload-error. So the absence of pipeline-error says nothing about whether processing succeeded.

UI telemetry

Emitted by every framework's UI layer with identical payloads (React is the payload canon). Useful for analytics on how people drive the picker.

React callback props

<UpupUploader> accepts these handlers. They come from the shared UploaderBaseProps type, so React, Vue, Svelte, Angular, and Preact all take the same set (each with its own binding syntax). Most are driven by a core event — subscribe to the event instead when you need the full payload, ordering guarantees, or a listener outside the component.

Vanilla is a different surface. @upupjs/vanilla's createUploader takes CreateUploaderOptions, not UploaderBaseProps, and accepts only eleven callbacks: onFileAdded, onFileRemoved, onUploadProgress, onUploadComplete, onDoneClicked, onIntegrationClick, onFilesDragOver, onFilesDragLeave, onFilesDrop, onWarn, onError. Note onFileAdded rather than onFilesSelected, and a single onUploadProgress rather than the per-file/aggregate pair. onStatusChange, onPrepareFiles, onRestrictionFailed, onFileTypeMismatch, and the per-file upload callbacks have no vanilla equivalent — subscribe to the events directly there.

onFilesUploadComplete and onUploadComplete are both invoked from upload-all-complete — pick one.

Caveats worth knowing

The rejection callbacks are UI-path only, and the reason is guessed from text. onFileTypeMismatch and onRestrictionFailed are not wired to restriction-failed. The built-in UI wraps its addFiles call in a try/catch and classifies the thrown error by substring-matching its message — 'type', 'limit', 'below', 'size' — to pick the reason code. Two consequences: calling core.addFiles() yourself emits restriction-failed but invokes neither callback, and the reason code is a heuristic over human-readable text rather than a structured field. For robust handling, subscribe to restriction-failed and inspect the error yourself. Both callbacks fire for a type mismatch; onRestrictionFailed alone covers the size and count cases.

Drag callbacks never receive files. onFilesDragOver and onFilesDragLeave are handed e.dataTransfer.files, which browsers keep empty during a drag (the DataTransfer is in protected mode until the drop completes). Expect [] and use these purely as hover signals — real files arrive only in onFilesDrop.

SSE processing is per batch, not per file. Despite its name and per-file signature, onFileProcessed is driven by a connection opened once the entire batch finishes: the handler folds into onFilesUploadComplete and then opens one EventSource per completed file. No connection opens after each individual upload, so with a long batch the first file's server-side processing isn't watched until the last file lands.

Next steps

• Event Handlers — the short version of the callback props.
• Headless Usage — drive UpupCore and its bus with no upup UI at all.
• Error Handling — the UpupError taxonomy behind upload-error.