ZipKit
Glossary

File API

File API is the W3C specification that lets a web page work with files the user picks, using the interfaces Blob, File, FileList and FileReader. A page reads a file in the browser without sending it to a server. It is the layer between an input element of type file and everything that handles bytes in JavaScript. The spec is an Editor's Draft maintained by the W3C Web Applications Working Group.

How it works

The spec defines four main pieces:

  • Blob: raw bytes with size and type. See the Blob term.
  • File: a Blob with a name (string) and lastModified (milliseconds since the Unix epoch, a long long). It inherits everything else from Blob.
  • FileList: an array-like list of File objects, with a length property and item(index) method. The spec marks it "at risk" because the platform trend is toward plain arrays.
  • FileReader: reads a Blob asynchronously, with events.

Users get File objects from input type=file (the files property), from drag and drop (dataTransfer.files) or from other APIs. You can also construct one in code with new File(parts, name, { type, lastModified }). If you omit lastModified, it defaults to the current time, equal to Date.now(). The constructor requires both the parts array and the name.

A File is immutable and represents the data at the moment a read begins. If the file no longer exists on disk when you read it, the read fails with an error, and the spec names NotFoundError for the synchronous reader in workers.

const f = new File(['abc'], 'a.txt', { type: 'text/plain', lastModified: 1767225600000 });
console.log(f.name, f.size, f.type, f.lastModified, new Date(f.lastModified).toISOString());
console.log(f instanceof Blob, Object.prototype.toString.call(f));
const g = f.slice(1); console.log(g instanceof File, g instanceof Blob, g.name);
try { new File(['x']); } catch (e) { console.log(e.name + ': ' + e.message); }

Output from Node 22.22.0:

a.txt 3 text/plain 1767225600000 2026-01-01T00:00:00.000Z
true [object File]
false true undefined
TypeError: The "fileBits" and "fileName" arguments must be specified

What is the difference between File and Blob?

A File is a Blob that also has a name and a lastModified time. Use Blob for anonymous data you generate, and File for something that should keep a file name, such as an upload. The slice() method on a File returns a plain Blob, so the name is lost, as the output above shows.

Does the File API upload files?

No. It only reads and represents them locally. To upload, put a File in FormData and send it with fetch, or pass it as the request body directly. The browser then sends the bytes and a multipart Content-Disposition filename.

Common pitfalls

  • Trusting file.type: it comes from the file extension or the page, not from sniffing content. Validate on the server.
  • Trusting file.name: it is chosen by the client, so treat it as untrusted input on the server and never use it directly as a storage path.
  • Treating a FileList as an array: it only has length and item(index), so map and filter do not exist. Use Array.from(input.files).
  • Reading a file that was deleted: the spec treats a read of a file that no longer exists as an error, so handle the error event.
  • Missing arguments to the constructor: new File(['x']) throws a TypeError because the name is required.

Related terms

  • Blob — the parent type holding bytes and MIME type.
  • FileReader — the event-based API for reading a File.
  • FormData — carries File objects in multipart uploads.
  • Fetch API — uploads a File as a body.
  • DOM — the input element and drag events that supply files.
  • Content-Type — the header that tells a server the media type of an upload.

See also