Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Web APIs in Node.js

Node.js FormData class

Reference for the FormData class in Node.js: add fields and files, send multipart/form-data with fetch(), and parse form bodies back into entries.

FormData is a list of name and value pairs that models an HTML form submission. Values are strings or files (Blob and File objects). When you pass a FormData object as the body of fetch(), Node encodes it as multipart/form-data with a generated boundary and sets the right Content-Type header for you.

It is also the way to read form bodies on the receiving side: request.formData() and response.formData() parse a multipart or urlencoded body into a FormData. FormData, File and Blob are globals in Node.js.

NODE
const form = new FormData();
form.append('name', 'Ada');
form.append('avatar', new Blob(['...']), 'ada.png');

Try it

Node.js Fields, repeated names and files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Sending multipart with fetch and reading it back

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new FormData()
Method Description
append(name, value[, filename]) Add an entry; existing entries with the same name stay.
set(name, value[, filename]) Replace all entries of that name with this one (or add it).
get(name) The first value for the name, or null.
getAll(name) An array of every value for the name.
has(name) true if an entry exists.
delete(name) Remove all entries of that name.
entries(), keys(), values(), forEach(), iteration Visit entries in insertion order.

value is a string, a Blob or a File. A Blob is wrapped in a File named blob unless you pass filename. Anything else is converted with String(). Passing a filename with a plain string is a TypeError.

Returns: append(), set() and delete() return undefined.

Errors: TypeError when called with too few arguments, or when filename is given for a non-Blob value. request.formData() rejects with TypeError when the body is not valid multipart or urlencoded data, or when the Content-Type is not a form type.

Usage notes

  • Never set Content-Type yourself when sending FormData with fetch(). The boundary is generated at send time and must match the header exactly.
  • Entries keep insertion order. Unlike Headers, nothing is sorted.
  • Values are not parsed. Everything that comes out of a parsed body is a string or a File, never a number.
  • Files are held in memory. Parsing a large upload with formData() reads the whole body first; for big uploads parse the stream with a dedicated streaming parser instead.
  • FormData is not a Map, and JSON.stringify(form) returns {}. Convert with Object.fromEntries(form) for a quick object view, remembering that repeated names collapse to the last value.
  • URLSearchParams is the urlencoded sibling. Use it for application/x-www-form-urlencoded bodies; fetch() sets the right type for it.
  • Treat parsed names and file names as untrusted input: validate and sanitize before touching the file system or a database.
  • There is no HTML form in Node, so the browser shortcut new FormData(formElement) does not apply; add entries yourself.