Next.js file upload progress with server actions and a route handler

A server action can take a file, but it can't tell the browser how much has been sent. For a real progress bar, send the file with XMLHttpRequest to a route handler that streams it to disk, then let a server action save the record. Below: the route, the progress helper, a plain progress bar with Cancel, the free Upload Dropzone wired to the same helper, the size limits to raise, and Hold to Delete for removing an uploaded file.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

The route handler that streams the file to disk

app/api/upload/route.ts

import { createWriteStream } from "node:fs";
import { mkdir, unlink } from "node:fs/promises";
import { join } from "node:path";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import type { ReadableStream as NodeReadableStream } from "node:stream/web";

export const runtime = "nodejs"; // streams to disk, so not the edge runtime

const MAX_BYTES = 200 * 1024 * 1024;
const DIR = join(process.cwd(), "uploads");

// The browser sends the raw file as the body (no FormData), so we can stream it
// to disk without holding it in memory. XMLHttpRequest reports progress on its side.
export async function POST(request: Request) {
  // check the session here before accepting anything
  const size = Number(request.headers.get("content-length") ?? 0);
  if (!size) return Response.json({ error: "Empty upload" }, { status: 400 });
  if (size > MAX_BYTES) return Response.json({ error: "Files up to 200 MB" }, { status: 413 });
  if (!request.body) return Response.json({ error: "No body" }, { status: 400 });

  const name = decodeURIComponent(request.headers.get("x-file-name") ?? "file").replace(/[^\w.-]/g, "_").slice(0, 120);
  const id = `${crypto.randomUUID()}-${name}`;
  const path = join(DIR, id);
  await mkdir(DIR, { recursive: true });

  try {
    // request.body is a web stream; Readable.fromWeb turns it into a Node stream for the file
    await pipeline(Readable.fromWeb(request.body as NodeReadableStream<Uint8Array>), createWriteStream(path));
  } catch {
    await unlink(path).catch(() => {}); // cancelled or broken upload: drop the partial file
    return Response.json({ error: "Upload interrupted" }, { status: 499 });
  }

  return Response.json({ id, name, size });
}

lib/upload-with-progress.ts

export type Uploaded = { id: string; name: string; size: number };

// fetch() has no upload progress event in browsers. XMLHttpRequest does:
// xhr.upload.onprogress fires as bytes leave the browser.
export function uploadWithProgress(file: File, onProgress: (pct: number) => void, signal?: AbortSignal): Promise<Uploaded> {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("POST", "/api/upload");
    xhr.setRequestHeader("x-file-name", encodeURIComponent(file.name));
    xhr.setRequestHeader("content-type", file.type || "application/octet-stream");
    xhr.responseType = "json";

    xhr.upload.onprogress = (e) => {
      if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
    };
    xhr.onload = () => {
      if (xhr.status >= 200 && xhr.status < 300) resolve(xhr.response as Uploaded);
      else reject(new Error((xhr.response as { error?: string } | null)?.error ?? `Upload failed (${xhr.status})`));
    };
    xhr.onerror = () => reject(new Error("Network error"));
    xhr.onabort = () => reject(new DOMException("Upload cancelled", "AbortError"));

    if (signal?.aborted) return reject(new DOMException("Upload cancelled", "AbortError"));
    signal?.addEventListener("abort", () => xhr.abort(), { once: true });

    xhr.send(file); // the raw file, which the route streams to disk
  });
}

app/upload/actions.ts

"use server";
import { unlink } from "node:fs/promises";
import { join } from "node:path";
import { revalidatePath } from "next/cache";
import type { Uploaded } from "@/lib/upload-with-progress";

const DIR = join(process.cwd(), "uploads");
const SAFE_ID = /^[0-9a-f-]{36}-[\w.-]+$/;

// Called after the route handler has the bytes. Write the row in your database here.
export async function saveUpload(file: Uploaded): Promise<void> {
  if (!SAFE_ID.test(file.id)) throw new Error("Bad file id");
  // await db.files.insert({ id: file.id, name: file.name, size: file.size, userId })
  revalidatePath("/upload");
}

// Removes a file the user uploaded. The id check keeps paths inside ./uploads.
export async function deleteUpload(id: string): Promise<{ error?: string }> {
  if (!SAFE_ID.test(id)) return { error: "Bad file id" };
  try {
    await unlink(join(DIR, id));
  } catch {
    return { error: "That file is already gone." };
  }
  revalidatePath("/upload");
  return {};
}

app/upload/upload-form.tsx

"use client";
import { useRef, useState } from "react";
import { uploadWithProgress, type Uploaded } from "@/lib/upload-with-progress";
import { saveUpload } from "./actions";

type State = { status: "idle" | "uploading" | "done" | "error"; pct: number; message?: string };

export function UploadForm() {
  const [state, setState] = useState<State>({ status: "idle", pct: 0 });
  const ctrl = useRef<AbortController | null>(null);

  async function onFile(file: File) {
    ctrl.current = new AbortController();
    setState({ status: "uploading", pct: 0 });
    try {
      const up: Uploaded = await uploadWithProgress(file, (pct) => setState({ status: "uploading", pct }), ctrl.current.signal);
      // the bytes are on the server; a server action records them with the user's session
      await saveUpload(up);
      setState({ status: "done", pct: 100, message: `${up.name} uploaded` });
    } catch (err) {
      const cancelled = err instanceof DOMException && err.name === "AbortError";
      setState({ status: cancelled ? "idle" : "error", pct: 0, message: cancelled ? undefined : (err as Error).message });
    }
  }

  return (
    <div className="grid max-w-md gap-3">
      <input type="file" disabled={state.status === "uploading"} onChange={(e) => e.target.files?.[0] && onFile(e.target.files[0])} />
      {state.status === "uploading" && (
        <div className="flex items-center gap-3">
          <progress max={100} value={state.pct} className="w-full" aria-label="Upload progress" />
          <span className="w-10 text-right text-sm tabular-nums">{state.pct}%</span>
          <button type="button" onClick={() => ctrl.current?.abort()} className="text-sm underline">
            Cancel
          </button>
        </div>
      )}
      {state.message ? <p role={state.status === "error" ? "alert" : "status"} className="text-sm">{state.message}</p> : null}
    </div>
  );
}

Good to know

Why not a server action for the bytes: the browser sends the whole form in one request and the action runs after it has arrived, so there is nothing to report while it uploads. fetch() has no upload progress event in browsers either. XMLHttpRequest does, through xhr.upload.onprogress, so the bytes go to a route handler and the server action only writes the record.
The browser sends the raw file as the body, not FormData. That lets the route stream it straight to disk with pipeline, without holding the file in memory, and the content-length header gives an early size check.
Cancel calls xhr.abort(). The route's pipeline then fails, and the catch deletes the partial file.
Check the user's session in the route before accepting the body. A route handler is a public endpoint, the same as a server action.
On a serverless host the local disk isn't kept. Point the stream at your storage instead, or upload straight to S3, R2 or Vercel Blob from the browser; the S3 and Blob guides linked below use the same progress idea.
What we ran on Oct 26 2026: every file on this page type-checks with TypeScript 5.9.3 against next 15.5.28, react 19.1.1, the free UploadDropzone and the shipped HoldToDelete. The route handler ran in Node 22: a 3 MB body came back 200 with the file written at full size, a 300 MB content-length got 413 and an empty request got 400. We didn't run the XMLHttpRequest helper in a browser for this page.

Small files: a server action with useActionState

For an avatar or a small image, a server action is simpler and a pending state is enough. useActionState gives you that pending flag and the action's answer.
Server actions refuse bodies over 1 MB by default. Raise it with experimental.serverActions.bodySizeLimit in next.config.ts. If your app has a middleware file, Next.js also cuts request bodies at 10 MB by default; experimental.middlewareClientMaxBodySize raises that one. Both names are from the Next.js 15.5 config types.

app/avatar/actions.ts

"use server";
import { writeFile, mkdir } from "node:fs/promises";
import { join } from "node:path";

export type AvatarState = { ok: boolean; message: string };

// Fine for small files. A server action gets the whole FormData at once,
// so the browser can show a pending state but not a percentage.
export async function uploadAvatar(_prev: AvatarState, formData: FormData): Promise<AvatarState> {
  const file = formData.get("avatar");
  if (!(file instanceof File) || file.size === 0) return { ok: false, message: "Pick an image first." };
  if (!file.type.startsWith("image/")) return { ok: false, message: "That isn't an image." };
  if (file.size > 4 * 1024 * 1024) return { ok: false, message: "Images up to 4 MB." };

  const dir = join(process.cwd(), "uploads", "avatars");
  await mkdir(dir, { recursive: true });
  await writeFile(join(dir, `${crypto.randomUUID()}.${file.type.split("/")[1] ?? "img"}`), Buffer.from(await file.arrayBuffer()));
  return { ok: true, message: "Avatar saved." };
}

app/avatar/avatar-form.tsx

"use client";
import { useActionState } from "react";
import { uploadAvatar, type AvatarState } from "./actions";

export function AvatarForm() {
  const [state, action, pending] = useActionState<AvatarState, FormData>(uploadAvatar, { ok: false, message: "" });
  return (
    <form action={action} className="grid max-w-sm gap-3">
      <input type="file" name="avatar" accept="image/*" required />
      <button type="submit" disabled={pending} className="rounded-md bg-black px-3 py-2 text-white disabled:opacity-60">
        {pending ? "Uploading..." : "Save avatar"}
      </button>
      {state.message ? <p role="status" className="text-sm">{state.message}</p> : null}
    </form>
  );
}

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    // server actions refuse bodies over 1 MB by default
    serverActions: { bodySizeLimit: "5mb" },
    // with a middleware file, request bodies are cut at 10 MB by default
    middlewareClientMaxBodySize: "200mb",
  },
};

export default nextConfig;

The free Upload Dropzone with real progress

Our Upload Dropzone is free and MIT licensed. Its upload prop takes (file, onProgress, signal), which is exactly the helper above, so every file gets its own progress ring driven by the real bytes. Removing a file mid-upload aborts its request through the signal.
Install it with the shadcn command on its page, or from npm as qodesign-free.

Get the free Upload Dropzone

app/upload/dropzone.tsx

"use client";
import UploadDropzone, { type Uploader } from "qodesign-free/upload-dropzone";
import { uploadWithProgress } from "@/lib/upload-with-progress";
import { saveUpload } from "./actions";

// The free Upload Dropzone takes (file, onProgress, signal). The same XHR helper
// fills each file's progress ring, and removing a file aborts its request.
const upload: Uploader = async (file, onProgress, signal) => {
  const up = await uploadWithProgress(file, onProgress, signal);
  await saveUpload(up);
};

export default function Dropzone() {
  return <UploadDropzone upload={upload} accept="image/*,.pdf,.zip" maxSize={200 * 1024 * 1024} />;
}

Where Hold to Delete fits

Once a file is up, people need a way to take it back. Hold to Delete is that step: the file shows as a card, a button you press and hold for 1.2 seconds crumples it into the bin, and an Undo toast stays for 5 seconds before anything is deleted.
Its onCommit runs only when the undo window is over, so that's where the delete action goes. If the delete fails, a new key puts the card back and the message says why.
The piece draws on a fixed 1000 by 660 stage. The small hook below scales it to the width of its box.

The same card with Supabase Storage

components/hold-stage.tsx

"use client";
import { useEffect, useState } from "react";

// Hold to Delete draws on a fixed 1000 x 660 stage. This scales it to the width of its box.
export function useHoldStage() {
  const [el, setEl] = useState<HTMLDivElement | null>(null);
  const [scale, setScale] = useState(0);
  useEffect(() => {
    if (!el) return;
    const ro = new ResizeObserver(([entry]) => setScale(entry.contentRect.width / 1000));
    ro.observe(el);
    return () => ro.disconnect();
  }, [el]);
  return { ref: setEl, scale };
}

app/upload/uploaded-file.tsx

"use client";
import { useState } from "react";
import HoldToDelete from "@/components/HoldToDelete";
import { useHoldStage } from "@/components/hold-stage";
import { deleteUpload } from "./actions";

// After the upload: the file as a card you press and hold to delete, with an undo window.
// deleteUpload only runs when the undo window is over.
export function UploadedFile({ id, name, size }: { id: string; name: string; size: number }) {
  const { ref, scale } = useHoldStage();
  const [attempt, setAttempt] = useState(0);
  const [message, setMessage] = useState("");
  const ext = name.includes(".") ? name.split(".").pop()!.slice(0, 4).toUpperCase() : "FILE";

  return (
    <section className="space-y-2">
      <div ref={ref} className="relative aspect-[1000/660] w-full overflow-hidden rounded-xl">
        {scale > 0 && (
          <HoldToDelete
            key={attempt}
            fileName={name}
            fileMeta={`${(size / 1048576).toFixed(1)} MB`}
            fileType={ext}
            tags={[]}
            emptyText="File deleted"
            restoreLabel={null}
            onCommit={async () => {
              const { error } = await deleteUpload(id);
              if (error) {
                setMessage(error);
                setAttempt((n) => n + 1); // a new key puts the card back
              }
            }}
            style={{ position: "absolute", left: 0, top: 0, transform: `scale(${scale})`, transformOrigin: "0 0" }}
          />
        )}
      </div>
      <p role="alert" className="text-sm text-red-600">{message}</p>
    </section>
  );
}

Install

Copy from the zipPut react/src/components into src/, then none for the upload. The dropzone and Hold to Delete need framer-motion.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

onCommit: the undo window ran out: delete the file here
fileName / fileMeta / fileType: the name, a size line and a short label like PDF
holdMs / undoMs: 1200 ms hold and 5000 ms undo by default
onUndo: Undo was pressed and nothing was sent

How qodesign compares

qodesign vs UiverseUiverse is best for: single small elements: buttons, loaders, toggles, checkboxes, inputs.
qodesign vs AnimataAnimata is best for: free animated building blocks you copy and adapt.
qodesign vs Motion PrimitivesMotion Primitives is best for: small motion building blocks you compose yourself: text effects, number tickers, dialogs, toolbars.

All comparisons, with prices read on each library's own site.

From the blog: Next.js File Upload: Server Actions, Progress Bars and the 1 MB Limit

From the blog: Fix "Failed to find Server Action" in Next.js After a Deploy

Questions

Can a Next.js server action show upload progress?

No. The action runs after the whole request has arrived, so there's nothing to report while the file uploads. Send the file with XMLHttpRequest to a route handler and read xhr.upload.onprogress.

Can I use fetch and still get upload progress?

Not in browsers today. fetch has no upload progress event, so the helper on this page uses XMLHttpRequest.

What is the file size limit for server actions?

1 MB by default. Raise it with experimental.serverActions.bodySizeLimit in next.config.ts, for example "5mb".

Why does my upload fail at 10 MB?

With a middleware file, Next.js cuts request bodies at 10 MB by default. Raise experimental.middlewareClientMaxBodySize, or keep the upload route out of the middleware matcher.

How do I cancel an upload?

Keep an AbortController per upload and call abort(). The helper passes it to xhr.abort(), and the route deletes the partial file.

Does Hold to Delete work in Next.js?

Yes, as a client component. Keep "use client" at the top of the file that renders it, as in the snippet above. App Router and Pages Router both work.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.