File Upload

Demo & usage

More examples

<sv-file-upload variant="button" size="sm" accept=".pdf,.docx" (fileAdded)="add($event)" />

<sv-file-upload-pro
  variant="dropzone"
  accept="image/*"
  [maxSizeMb]="5"
  (filesChange)="onFiles($event)"
  (uploadError)="onReject($event)" />

import { svChunkedUploader } from '@styloviz-pro/file-upload';

upload = svChunkedUploader({
  // How many bytes the server already has. Optional; a failure here just means
  // starting from the beginning rather than failing the upload.
  probe: ({ key, signal }) =>
    fetch(`/api/uploads/${key}`, { signal })
      .then(r => (r.ok ? r.json().then(j => j.bytes) : 0)),

  sendChunk: ({ key, blob, chunk, signal }) =>
    fetch(`/api/uploads/${key}`, {
      method: 'PATCH',
      headers: { 'Upload-Offset': String(chunk.start) },
      body: blob,
      signal,
    }).then(r => {
      // Attach the status so the retry policy can read it: a 503 is retried,
      // a 413 is not — retrying a body that is over the limit uploads it in
      // full, five times, to fail identically every time.
      if (!r.ok) throw Object.assign(new Error(r.statusText), { status: r.status });
    }),

  complete: ({ key, signal }) =>
    fetch(`/api/uploads/${key}/complete`, { method: 'POST', signal }).then(r => r.json()),
});

<sv-file-upload-pro [uploader]="upload" [maxSizeMb]="5000" />

<sv-file-upload-pro pasteToUpload="page" accept="image/*" />

// Every pasted screenshot arrives named image.png, so three pastes would
// collide on the server. They are renamed from the clock and their ordinal:
//   pasted-2026-08-17-101530.png
//   pasted-2026-08-17-101530-2.png

<sv-file-upload-pro
  [directory]="true"
  accept="image/*"
  [maxScannedFiles]="20000"
  (intakeSkipped)="notice.set($event)" />

// Each file keeps the path it had inside the folder, so three folders each
// holding an IMG_0001.jpg stay distinguishable.
files()[0].path;   // 'trip/day1/IMG_0001.jpg'

// intakeSkipped reports what was left behind — .DS_Store, the accept filter,
// or the scan limit. A folder drop that quietly loses files is
// indistinguishable from a broken component.

<sv-file-upload-pro #upload accept="image/*" [cropImages]="true" />

@let held = upload.cropQueue()[0];
@if (held && held.preview) {
  <sv-image-cropper #cropper [src]="held.preview" [aspect]="1" />
  <button (click)="upload.applyCrop(held.id, await cropper.cropImage())">Crop</button>
  <button (click)="upload.skipCrop(held.id)">Use the original</button>
}

// canvas.toBlob falls back to image/png when it cannot write the type it was
// handed — silently, with no error and no flag. The blob's own type therefore
// wins over the request, or photo.webp ends up full of PNG bytes.
svCropReplacement(original, pngBlob, { type: 'image/webp' }).name;  // 'photo.png'

// HEIC, TIFF and SVG are never offered a cropper: an <img> pointed at an HEIC
// outside Safari never fires load, so the cropper sits blank forever with no
// error to react to. They upload untouched.
svIsCroppableImage({ type: 'image/heic' });   // false

// form = new FormGroup({ docs: new FormControl<File[]>([]) });
<sv-file-upload formControlName="docs" accept=".pdf" />

<!-- or template-driven -->
<sv-file-upload [(ngModel)]="docs" />

import { svChunkedUploader, svLocalResumeStore, svCanResume } from '@styloviz-pro/file-upload';

const store = svLocalResumeStore({ scope: currentUser.id });
store.prune(24 * 60 * 60 * 1000);

uploader = svChunkedUploader({
  probe: async ({ file, key, signal }) => {
    const saved = store.get(key);
    if (svCanResume(saved, file)) {
      const res = await fetch(saved!.uploadUrl, { method: 'HEAD', signal });
      if (res.ok) return Number(res.headers.get('Upload-Offset') ?? 0);
    }
    const created = await fetch('/api/uploads', { method: 'POST', signal });
    store.set({ key, uploadUrl: created.headers.get('Location')!, size: file.size,
                lastModified: file.lastModified, createdAt: Date.now() });
    return 0;
  },
  sendChunk: ({ key, blob, chunk, signal }) =>
    fetch(store.get(key)!.uploadUrl, { method: 'PATCH', body: blob, signal,
      headers: { 'Upload-Offset': String(chunk.start) } }).then((r) => {
      if (!r.ok) throw Object.assign(new Error(r.statusText), { status: r.status });
    }),
  complete: async ({ key }) => { store.remove(key); },
});

When to use

• Letting users attach files via drag-and-drop or a button trigger.
• You need type/size constraints and per-file progress out of the box.
• Use the dropzone variant for media-heavy flows, the button variant in tight toolbars.

Async states

None — this component has nothing to load, so it has no loading, empty or error state to drive.

Outputs

<sv-file-upload-pro>

Also in this family — SvFileUploadProComponent from @styloviz-pro/file-upload.

Inputs

Outputs

Customization & theming

• Choose `variant` (dropzone · compact · button) and `size`; the free tier ships the button variant.
• Constrain with `accept`, `maxSizeMb`, `maxFiles` and `multiple`; wire a real backend with the `uploader` function (progress, cancel via AbortSignal, retry, concurrency limit).
• React to `filesChange`, `fileAdded`, `fileRemoved`, `uploadComplete` and `uploadError`, or bind the `File[]` value with a reactive control (CVA).
• Chunked and resumable uploads (Pro) via `svChunkedUploader`. `svPlanChunks`, `svResumePlan`, `svIsRetryableStatus`, `svRetryDelay`, `svChunkProgress` and `svUploadKey` are exported for hosts with their own transport.
• Paste-to-upload (Pro) via `pasteToUpload` (`off` · `zone` · `page`), and folder upload via `directory` and `maxScannedFiles`, with `intakeSkipped` reporting what an intake left behind. `svExpandDrop`, `svReadDirectory`, `svNamePastedFiles` and `svFilterIntake` are exported.

Best practices

• Do: Constrain `accept` and `maxSizeMb` so failures surface immediately — they are enforced on drop too.
• Don't: Don't treat `accept` as a security check. It matches an extension out of a filename the user chose, or a `File.type` the browser derived from that same extension — so `payload.exe` renamed `photo.png` passes `accept=".png"` and reports `image/png`. Nothing here reads the bytes, and `curl` is not running this filter at all. Validate the type on the server, from the bytes, at the point of storage.
• Do: Report a malware verdict with `markScanning(id)` and `markScanned(id, verdict, reason?)` if you scan. The upload succeeding and the file being safe are different facts arriving seconds apart, and without the second one the row says "Uploaded" with a green tick while the scanner is still thinking.
• Do: Set `scanPolicy="required"` (Pro) when you scan. It is what keeps an uncleared file out of the form value — the thing a submit handler actually reads — so the rest of the UI being honest is not left carrying the whole job. A flagged file is excluded under either policy.
• Don't: Don't expect a flagged file to appear in `errorCount` or offer a Retry. Its `status` stays `'success'` because the upload worked and the content is the problem; a retry would re-send bytes the server has already looked at and rejected. `flaggedCount()` is the one to read.
• Do: Reflect progress and errors per file using the `uploadComplete` / `uploadError` events.
• Do: Bind with `formControlName` / `[(ngModel)]` when you need the `File[]` as part of a form; the event API stays available for progress/validation UX.
• Do: Surface `intakeSkipped` after a folder drop. A user who drops 250 photos and sees 180 queue, with nothing saying which 70 went or why, cannot tell your filter from a bug.
• Do: Have the server verify the length of a resumed upload. `svUploadKey` is name + size + lastModified, which is a hint rather than an authority — two different files can collide, and a client-side key is not something to append bytes on the strength of.
• Don't: Don't raise `concurrency` on `svChunkedUploader` unless your endpoint takes an explicit range or part number. Append-only endpoints store parallel chunks in arrival order, and the file uploads cleanly, reports success, and is a shuffle of itself.
• Don't: Don't silently drop rejected files — the component marks them as errors so you can tell the user why.
• Do: Persist the upload handle if you want resume to survive a reload. `svResumePlan` works out what is left to send GIVEN a server offset — but asking the server for that offset means knowing which upload to ask about, and that handle used to live only in a JavaScript variable. `svLocalResumeStore` writes it down; `svCanResume` checks a stored record against the file in hand before you trust it.
• Don't: Don't use the resume store without a `scope`. An upload URL is a capability, and `localStorage` is scoped to an ORIGIN rather than to a user — on a shared machine, or after a logout that does not clear storage, the next person can resume the previous person's upload. Pass the account id. It is not encryption; it is the difference between "anybody on this browser" and "this account on this browser".
• Do: Call `prune()` on startup. A record is written per upload and removed on completion, so abandoned uploads leave theirs behind forever — and `localStorage` is a few megabytes shared with everything else your origin stores.

Accessibility

• Focus after a mutation (X-12): removing a file moves focus to the Remove button of the file that took its place, then the one before it, then the control that adds files; Clear all goes to that control. A host calling `removeFile()` programmatically does not move focus.
• Keyboard-accessible `role="button"` dropzone (Enter/Space opens the dialog) with a visible focus ring; disabled removes it from the tab order and disables the row actions.
• File add/remove/upload status is announced through a visually-hidden `aria-live="polite"` region; progress bars expose `role="progressbar"` with `aria-valuenow`/`min`/`max`.
• The `accept` filter is enforced on drag-and-drop as well as the picker — non-matching files are flagged as errors rather than accepted.
• Paste-to-upload never swallows a text paste and never calls preventDefault on one, so copying a URL and pressing Ctrl+V on a page that happens to contain an upload zone keeps working. In `page` mode a paste aimed at an editable element is ignored outright.
• Each file row exposes labelled retry/remove controls.
• Implements ControlValueAccessor — the value is `File[]`; works with `[(ngModel)]`, `[formControl]` and `formControlName`, and `formControl.disable()` disables the field.