Validating File Type and Size Before Upload

A size or type limit enforced only by the server is discovered after the upload — which for a 150 MB phone video on a mobile connection means minutes of waiting followed by “File too large”, and for a .pdf that is really a renamed Word document means a confusing processing failure an hour later.

The file upload fields lifecycle puts local validation between selected and uploading. Everything about a file that matters for acceptance — its size, its real format, an image’s pixel dimensions — can be read locally in milliseconds. This page implements those checks in order of cost, with messages that tell the user exactly which file failed and what to do.

Context and prerequisites

Three sources of type information exist, with very different reliability:

• The accept attribute on the input filters the file picker. It is a hint to the picker, not a validation: users can switch the picker to “All files”, and drag-and-drop ignores it entirely.
• file.type is the MIME type the browser guessed from the file name extension (and the operating system’s registry). A file renamed from .docx to .pdf reports application/pdf. Some files report an empty string.
• The first bytes of the file — its “magic number” — identify most formats reliably: %PDF- for PDF, 89 50 4E 47 for PNG, FF D8 FF for JPEG, 50 4B 03 04 for ZIP-based formats (including DOCX and XLSX).

Size is exact (file.size in bytes) and free. Image dimensions require decoding the header, which createImageBitmap does quickly without drawing anything. Run the checks cheapest first and stop at the first failure.

The core pattern: ordered checks returning a specific reason

export interface FileRules {
  maxBytes: number;
  types: { mime: string; ext: string[]; magic: number[][] }[];   // allowed formats
  image?: { minWidth?: number; minHeight?: number; maxPixels?: number };
}

export const PDF = { mime: "application/pdf", ext: [".pdf"], magic: [[0x25, 0x50, 0x44, 0x46, 0x2d]] };
export const PNG = { mime: "image/png", ext: [".png"], magic: [[0x89, 0x50, 0x4e, 0x47]] };
export const JPEG = { mime: "image/jpeg", ext: [".jpg", ".jpeg"], magic: [[0xff, 0xd8, 0xff]] };

const fmtBytes = (n: number) =>
  n >= 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(n >= 10 * 1024 * 1024 ? 0 : 1)} MB` : `${Math.ceil(n / 1024)} KB`;

export async function checkFile(file: File, rules: FileRules): Promise<string | null> {
  // 1. Size: exact and free. Check first so a huge file is never read.
  if (file.size === 0) return `${file.name} is empty.`;
  if (file.size > rules.maxBytes) {
    return `${file.name} is ${fmtBytes(file.size)}. Files must be ${fmtBytes(rules.maxBytes)} or smaller.`;
  }

  // 2. Extension and declared type: cheap, catches most honest mistakes.
  const ext = file.name.slice(file.name.lastIndexOf(".")).toLowerCase();
  const byExt = rules.types.find((t) => t.ext.includes(ext));
  const allowedList = rules.types.map((t) => t.ext[0].slice(1).toUpperCase()).join(", ");
  if (!byExt) return `${file.name} is not a supported file type. Use ${allowedList}.`;

  // 3. Signature: read only the first bytes; slice() does not load the file.
  const head = new Uint8Array(await file.slice(0, 16).arrayBuffer());
  const matches = (sig: number[]) => sig.every((b, i) => head[i] === b);
  if (!byExt.magic.some(matches)) {
    return `${file.name} does not look like a ${byExt.ext[0].slice(1).toUpperCase()} file. It may have been renamed; open and re-save it, then try again.`;
  }

  // 4. Image dimensions: decode the header only when rules ask for it.
  if (rules.image && byExt.mime.startsWith("image/")) {
    let bmp: ImageBitmap | undefined;
    try {
      bmp = await createImageBitmap(file);
      const { width, height } = bmp;
      const r = rules.image;
      if ((r.minWidth && width < r.minWidth) || (r.minHeight && height < r.minHeight)) {
        return `${file.name} is ${width}×${height} pixels. Images must be at least ${r.minWidth ?? 0}×${r.minHeight ?? 0}.`;
      }
      if (r.maxPixels && width * height > r.maxPixels) {
        return `${file.name} is too large in dimensions (${width}×${height}). Resize it and try again.`;
      }
    } catch {
      return `${file.name} could not be read as an image. It may be damaged.`;
    } finally {
      bmp?.close();   // release decoded memory immediately
    }
  }
  return null;
}

Step-by-step walkthrough

1. Set accept for the picker, but do not rely on it. accept=".pdf,image/png,image/jpeg" narrows the default view; drag-and-drop and “All files” bypass it, so the same rules run in code.
2. Check size before reading anything. file.size is exact and costs nothing; a 2 GB file should be rejected before a single byte is read.
3. Check the extension against an allow-list. This catches the common mistake (a .heic photo where JPEG is needed) with a message that lists what is accepted.
4. Read the first bytes and match signatures. file.slice(0, 16) creates a view without loading the file; arrayBuffer() on the slice reads 16 bytes.
5. Decode image headers only when dimensions matter. createImageBitmap is fast and off-main-thread in most browsers; always close() the bitmap.
6. Return one specific message naming the file. “photo.heic is not a supported file type. Use PDF, PNG, JPG.” Put it on the file’s item in the list, and in the error summary, following writing error messages that tell the reader what to do.

Failure modes and edge cases

1. file.type is empty

Files with unusual extensions, and some files from cloud-storage pickers, report type === "". Do not reject on an empty type; rely on the extension and signature instead.

2. HEIC photos from iPhones

iOS may convert HEIC to JPEG when a web page’s accept lists only JPEG, but not in every picker path, and files transferred to a desktop stay HEIC. Either accept HEIC and convert server-side, or reject with a message that explains how to export as JPEG.

3. Multiple files, one failure

When five files are dropped and one fails, keep the four that pass and show the one failure on its own item. Rejecting the whole drop makes the user re-select four good files.

4. The same message for every limit

“Invalid file” tells the user nothing. Size, type, damage and dimensions each need their own sentence, and each should include the actual value and the limit, so the user knows how far off they are.

5. Validation that blocks the main thread

Reading a whole large file with FileReader.readAsDataURL to “check” it can freeze the page and multiply memory use. Read only the bytes you need with slice, and never base64-encode a file just to validate it — previews are covered in image previews with object URLs without leaks.

Verification checklist

• A file one byte over the limit is rejected before any network request, with its size and the limit.
• Dragging a file of the wrong type onto the field is rejected even though the picker’s accept would have hidden it.
• A PNG renamed to .pdf is rejected with the “may have been renamed” message.
• Files with an empty file.type are judged by extension and signature, not rejected outright.
• An image below the minimum dimensions reports its actual size.
• When several files are chosen, valid ones proceed and each invalid one shows its own message.
• No check reads more than the bytes it needs; the page stays responsive with very large files.
• The server enforces the same limits and its rejections use the same wording.

Frequently Asked Questions

Related

• File Upload Fields and Binary State
• Upload Progress and Cancellation With XHR and Fetch
• Mapping Validation Errors to UI Components

← File Upload Fields and Binary State