File Uploader

Installation

$ npx gbs-add-block@latest -a FileUploader -beta

The block copies the file-uploader folder into your project, along with the small shared folder that every component imports. You own the code and can change it freely. There are no peer dependencies other than React.

Requirements

• React 19 and @types/react 19
• TypeScript target ES2022 or newer, with "jsx": "react-jsx"
• Browsers from 2024 or newer (the styles use light-dark(), :has() and :dir())

Import the stylesheet once, for example in your global CSS:

@import "../component-lib/gbs.css";

or in your root layout / entry file:

import "@/component-lib/gbs.css";

The FileUploader lets people drop, browse or paste files, checks them against your rules, and uploads them to your server in chunks. Each file shows its own progress and can be paused, resumed, retried or canceled. Several files upload at once, and failed chunks are retried with backoff. Image previews can be turned on or off, and files already on the server can be listed with download links. Without an endpoint it works as a better <input type="file"> inside a normal form.

Default

Quick Start

"use client";
 
import { FileUploader } from "@/component-lib/file-uploader";
 
export default function Attachments() {
  return (
    <FileUploader
      label="Attachments"
      multiple
      accept=".pdf,image/*"
      maxSize={20 * 1024 * 1024}
      endpoint="/api/upload"
      onUploadComplete={(items) =>
        console.log(items.map((item) => item.response))
      }
    />
  );
}

Selected files wait for the Upload button. Start them yourself with ref.current.upload(), or right away with autoUpload.

In this section

This page covers the component: installing it, its props, and everything that happens in the browser. The server side is long enough to live on its own page.

Props Table

Selection

Uploading

Display and Form

Events

UploadItem

interface UploadItem {
  id: string; // stable row key
  uploadId: string; // sent with every chunk; new after a cancel
  file: File;
  status:
    | "idle"
    | "queued"
    | "uploading"
    | "paused"
    | "success"
    | "error"
    | "canceled";
  uploadedBytes: number;
  progress: number; // 0 to 1
  chunkSize: number;
  chunksDone: number;
  totalChunks: number;
  error?: string;
  response?: unknown; // the server's answer to the latest chunk
}

Previews

With preview (the default), image files show a thumbnail. Set preview={false} to show type icons only, for example for sensitive documents or long lists.

• Thumbnails use object URLs, not base64. The browser doesn't copy the file into memory, and each URL is released when its row disappears.
• Formats the browser can't draw, such as HEIC in most browsers, fall back to the image icon.
• Other files show an icon for their kind: image, video, audio, PDF, spreadsheet, document, archive or other.

Existing Files

Show files saved earlier, for example when editing a record. The component doesn't fetch them; load them your way and pass them in:

const [existing, setExisting] = useState<ExistingFile[]>(record.attachments);
 
<FileUploader
  multiple
  endpoint="/api/upload"
  existingFiles={existing}
  onRemoveExisting={(file) =>
    setExisting((files) => files.filter((f) => f.id !== file.id))
  }
/>;

interface ExistingFile {
  id: string;
  name: string;
  size?: number;
  type?: string;
  url?: string; // download link, and the preview for images
}

Validation

Files are checked when they are dropped, picked or pasted. Rejected files are listed with a reason, and onRejected receives them:

<FileUploader
  accept="image/*"
  validate={(file) =>
    file.name.length > 100 ? "File names can be up to 100 characters" : null
  }
/>

Client checks are for the user's convenience only. Check type and size on the server as well.

Forms

With a name, the uploader takes part in a normal form. What it posts depends on whether it uploads:

Without an endpoint, a Server Action receives the files directly:

async function save(formData: FormData) {
  "use server";
  const files = formData.getAll("attachments") as File[];
}
 
<form action={save}>
  <FileUploader name="attachments" multiple />
  <button type="submit">Save</button>
</form>;

For large files, prefer an endpoint: chunks can resume, and Server Actions usually cap the body at 1 MB by default.

Imperative API (ref)

const uploader = useRef<FileUploaderHandle>(null);
 
<FileUploader ref={uploader} endpoint="/api/upload" multiple />;
 
const items = await uploader.current?.upload();

Keyboard

Accessibility: the drop zone is a real button whose name combines the label and the call to action, and whose hint lists the accepted types and limits. Each file's progress is a role="progressbar", and every row button is labelled with the file name ("Pause report.pdf"). Rejections are announced as alerts, and finished or failed uploads through a status region.

Styling and Theming

Rules ship unlayered, so a framework reset cannot strip them and a utility class passed through className still overrides them. Import the generated gbs.css once — see Theming.

<FileUploader classNames={{ dropzone: "min-h-40", item: "shadow-sm" }} />

CSS variables

Override them on .fu-root, on :root, or through style. Each variable falls back to the shared --gbs-* of the same name, then to the DataGrid's --dg-* when that stylesheet is loaded, and finally to the built-in palette.

Dark mode

Colors follow the page's color-scheme. To force a scheme, put class="dark" or data-theme="dark" (or "light") on an ancestor such as <html>.

Data attributes

Locale Text

<FileUploader
  locale="de-DE"
  localeText={{
    dropzone: "Dateien hierher ziehen oder",
    browse: "durchsuchen",
    upload: (count) => `${count} hochladen`,
    rejectTooLarge: (name, max) => `${name} ist größer als ${max}`,
  }}
/>

File sizes and percentages follow locale.

Core Exports

useFileUploader(config) returns { store, items, rejections } for building a different UI on the same engine:

const { store, items } = useFileUploader({
  multiple: true,
  transport: createHttpTransport({ endpoint: "/api/upload" }),
});
 
<input
  type="file"
  multiple
  onChange={(event) => store.addFiles(event.target.files ?? [])}
/>;
<button onClick={() => store.upload()}>Upload</button>;

The framework-free core is exported from @/component-lib/file-uploader/core:

Next.js

The component is a client component, and "use client" is already at the top of the files that need it. Upload to a Route Handler (see Server Implementation) rather than a Server Action: Server Actions buffer the whole body and are limited to 1 MB by default, while chunks keep every request small and resumable.

Nothing runs on the server: the store is created on the client, and no browser APIs are touched while rendering.

Migrating from the Previous Uploader

Notes

• Chunks of one file are sent in order. Parallelism is across files.
• Pausing aborts the chunk in flight, which is sent again on resume.
• Progress is kept in memory: a page reload starts files over, although the server may still hold earlier chunks under the old uploadId.
• Dropping a folder doesn't add the files inside it.