HTML File API — Complete Guide

File API lets web‑apps read, slice, stream and upload local files entirely in the browser—without server round‑trips until you decide.

• File — metadata wrapper for a Blob plus name, lastModified.
• Blob — immutable byte‑sequence; parent of File.
• FileReader — async utility that converts a Blob/File to text, DataURL or ArrayBuffer.
• DataTransfer/DragEvent — collect dropped files.
• FormData — packages files for XHR/Fetch uploads.

Note: All tasks are asynchronous by design—UI remains responsive while I/O occurs on a background thread.

2.1 File  element

<input type="file" id="pick" multiple accept="image/*">

Attribute	Description
multiple	Allow multi‑selection (returns FileList)
accept	MIME(s)/extensions filter (e.g. image/*, .pdf)
capture	Mobile hint to open camera/mic (environment|user)

2.2 Drag & Drop

dropZone.addEventListener('drop', (e) => {
  e.preventDefault();
  const files = [...e.dataTransfer.files];             // ← FileList → Array
});

3.1 Properties (File)

• name: string — base filename (no path)
• type: string — MIME (e.g. image/png)
• size: number — bytes
• lastModified: DOMTimeStamp — epoch ms

3.2 Common Methods (Blob)

blob.slice([start], [end], [contentType])	Returns a new Blob with byte‑range [start, end)
blob.stream()	ReadableStream for progressive reading (large files)
blob.arrayBuffer()	Promise → ArrayBuffer
blob.text()	Promise → string (UTF‑8 by default)

4.1 Typical Pattern

const reader = new FileReader();
reader.onload = ({ target }) => console.log(target.result);
reader.onerror = ({ target }) => console.error(target.error);
reader.readAsText(file, 'utf-8');

4.2 Method Reference

Method	Parameters	Result (reader.result)
readAsText(blob, [encoding])	blob — Blob|File encoding — UTF‑8 default; e.g. 'ISO-8859-2'	string
readAsArrayBuffer(blob)		ArrayBuffer
readAsDataURL(blob)		data:<mime>;<base64>

Note: Prefer the promise‑based blob.text()/arrayBuffer() when you don’t need legacy IE support.

5.1 Reading a Range

// first 1 MiB
const slice = file.slice(0, 1 * 1024 * 1024);
const text  = await slice.text();

5.2 Streaming Large Files

for await (const chunk of file.stream()) {
  processChunk(chunk);               // Uint8Array
}

Tip: Streams keep memory usage flat—vital for multi‑GB video editing in browser.

6.1 Fetch + FormData

const fd = new FormData();
fd.append('avatar', file, file.name);

await fetch('/upload', {
  method: 'POST',
  body: fd
});

6.2 Progress Events (XMLHttpRequest)

const xhr = new XMLHttpRequest();
xhr.upload.onprogress = (e) => {
  if (e.lengthComputable) updateBar(e.loaded / e.total);
};
xhr.open('POST', '/upload');
xhr.send(fd);

Parameter Notes

• Content‑Type header must be omitted—browser sets multipart/form-data with proper boundary.
• CORS pre‑flight required if custom headers are added.

7.1 WritableStream (Chrome 102+)

const writable = await fileHandle.createWritable();
await writable.write(blob);
await writable.close();

7.2 Secure Context Requirements

• Site must be served over HTTPS.
• User gesture required (showOpenFilePicker())

Note: These APIs are origin‑private; they cannot access arbitrary OS paths.

• Never trust file.type; sniff server‑side.
• Scan uploads for malware (e.g., ClamAV).
• Use Content‑Security‑Policy to forbid inline scripts inside previews.
• Enforce size limits client & server; reject oversized files early.

• Prefer streams + Web Workers for CPU‑heavy parsing (e.g., ZIP).
• Use requestIdleCallback to batch UI updates while reading.
• Cache processed items in IndexedDB to avoid re‑reads.

Class	Key Methods	Return Type
Blob	arrayBuffer()	Promise<ArrayBuffer>
File	slice(start,end)	Blob
FileReader	readAsDataURL()	void
FileSystemFileHandle	createWritable()	Promise<WritableStream>