FileUpload

Code

import { FileUpload, type FileUploadControls, type UploadFile } from "@fadymondy/nasaq/web";function send(item: UploadFile, controls: FileUploadControls) {  const body = new FormData();  body.append("file", item.file);  const xhr = new XMLHttpRequest();  xhr.open("POST", "/api/files");  xhr.upload.onprogress = (e) =>    controls.update(item.id, { status: "uploading", progress: Math.round((e.loaded / e.total) * 100) });  xhr.onload = () =>    controls.update(item.id, xhr.status < 300 ? { status: "done", progress: 100 } : { status: "error", error: "Upload failed" });  xhr.onerror = () => controls.update(item.id, { status: "error", error: "Network error" });  xhr.send(body);}export function Attachments() {  return (    <FileUpload      accept="image/*,.pdf"      maxSize={5 * 1024 * 1024}      maxFiles={4}      onFiles={(added, controls) => added.forEach((f) => send(f, controls))}      onRetry={send}    />  );}

Files · beta

Live examples and controls: FileUpload in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/file-upload.json

Choose files by clicking, pressing a key or dragging them in, see each one with its size and progress, and remove or retry it. Nasaq does not send anything: your onFiles callback starts the request and reports progress by patching the file's state, so it works with any transport (fetch, XHR, a presigned URL, tus).

When to useCopy Anchor Link

• Attachments, documents, imports: FileUpload.
• A profile or product picture: ImageUpload.
• Your own list or layout: Dropzone alone.

When not to useCopy Anchor Link

• Picking one value from a list: use Select.
• Showing progress of something that is not a file: use Progress.

ImportCopy Anchor Link

import { FileUpload, ImageUpload, Dropzone } from "@fadymondy/nasaq/web";

Quick startCopy Anchor Link

import { FileUpload, type FileUploadControls, type UploadFile } from "@fadymondy/nasaq/web";

function send(item: UploadFile, controls: FileUploadControls) {
  const body = new FormData();
  body.append("file", item.file);
  const xhr = new XMLHttpRequest();
  xhr.open("POST", "/api/files");
  xhr.upload.onprogress = (e) =>
    controls.update(item.id, { status: "uploading", progress: Math.round((e.loaded / e.total) * 100) });
  xhr.onload = () =>
    controls.update(item.id, xhr.status < 300 ? { status: "done", progress: 100 } : { status: "error", error: "Upload failed" });
  xhr.onerror = () => controls.update(item.id, { status: "error", error: "Network error" });
  xhr.send(body);
}

export function Attachments() {
  return (
    <FileUpload
      accept="image/*,.pdf"
      maxSize={5 * 1024 * 1024}
      maxFiles={4}
      onFiles={(added, controls) => added.forEach((f) => send(f, controls))}
      onRetry={send}
    />
  );
}

AnatomyCopy Anchor Link

FileUpload                     data-slot="file-upload"
├─ Dropzone                    data-slot="dropzone"  (data-dragging, data-invalid, data-disabled)
├─ ul (rejections, role=alert) data-slot="file-upload-errors"
└─ UploadList                    data-slot="file-list"
   └─ UploadListItem             data-slot="file-list-item"  (data-status)
      └─ Progress              while pending or uploading

ImageUpload                    data-slot="image-upload"
├─ preview (img + remove)      data-slot="image-upload-preview"
└─ Dropzone

APICopy Anchor Link

FileUploadCopy Anchor Link

FileUploadControlsCopy Anchor Link

UploadFileCopy Anchor Link

DropzoneCopy Anchor Link

FileRejection is { file: File; code: "too-large" | "wrong-type" | "too-many"; message: string } with a localised message.

UploadList / UploadListItemCopy Anchor Link

ImageUploadCopy Anchor Link

HelpersCopy Anchor Link

ExamplesCopy Anchor Link

Controlled, with a saved avatar:

import { ImageUpload } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function Avatar() {
  const [file, setFile] = useState<File | null>(null);
  return (
    <ImageUpload value={file} onValueChange={setFile} src="/avatars/current.png" alt="Profile picture" maxSize={2 * 1024 * 1024} />
  );
}

Arabic copy for your own errors:

controls.update(item.id, { status: "error", error: "انقطع الاتصال أثناء الرفع." });

AccessibilityCopy Anchor Link

• The dropzone is role="button" and described by the accepted types and size limit.
• Rejections render in a role="alert" list, so they are announced.
• Every row button is named with the file name ("Remove report.pdf"). Each Progress is named "report.pdf · Uploading".
• You localise: alt on ImageUpload, children prompts and the error text you set.

RTL & i18nCopy Anchor Link

• Built-in strings (prompt, statuses, limits, validation messages, size units) follow the Nasaq locale in English and Arabic.
• Sizes use Nasaq number formatting (Western digits by default). File names are wrapped in <bdi>, so an English name inside Arabic text keeps its order.
• The remove button on an image sits at the inline end and mirrors; progress fills from the inline start.

Styling & tokensCopy Anchor Link

Uses border-input, bg-card, bg-nq-hover, bg-nq-selected, border-nq-focus and text-nq-danger-text. Target [data-dragging], [data-invalid], [data-disabled] on the dropzone and [data-status] on rows. Extend with className; never override colours with raw hex.

Do / Don'tCopy Anchor Link

• Do validate again on the server: accept and maxSize are conveniences, not security.
• Do give every failed file an error message that says what to do.
• Do not start uploads during render; start requests from onFiles.
• Do not revoke object URLs by hand; useObjectUrl does it.

RelatedCopy Anchor Link

• Progress
• Button
• Field

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-files-file-upload--docs