Sending Form Data with FormData API

Technical Deep Dive & Specifications

Initializing FormData

You can initialize a FormData object in two ways:

1. From an HTML Form Element (Automatic Harvesting)

const formElement = document.querySelector('#profile-form');
const formData = new FormData(formElement);

• Automatically traverses all form controls (<input>, <select>, <textarea>).
• Extracts values from controls that have a valid name attribute.
• Rules of exclusion: Elements with disabled, inputs without a name attribute, and unchecked radio/checkboxes are automatically skipped.

2. Programmatically from Scratch

const formData = new FormData();
formData.append('username', 'alex');
formData.append('timestamp', Date.now());

The Complete FormData Method Matrix

+-----------------------------------------------------------------------------+
|                          FormData API METHODS                               |
+-----------------------------------------------------------------------------+
| Method                          | Description                               |
+---------------------------------+-------------------------------------------+
| formData.append(name, value)    | Appends a value. If key exists, adds      |
|                                 | another entry with the same key.          |
|                                 |                                           |
| formData.append(name, blob, fn) | Appends a Blob/File with custom filename. |
|                                 |                                           |
| formData.set(name, value)       | Overwrites any existing value for key,    |
|                                 | or creates it if not present.             |
|                                 |                                           |
| formData.get(name)              | Returns the first value for given key.    |
|                                 |                                           |
| formData.getAll(name)           | Returns an Array of all values for key.   |
|                                 |                                           |
| formData.has(name)              | Returns true if key exists in payload.    |
|                                 |                                           |
| formData.delete(name)           | Removes the key and all associated values.|
|                                 |                                           |
| formData.entries()              | Returns an iterator of [key, value] pairs.|
+-----------------------------------------------------------------------------+

The Fatal Fetch Header Mistake

A very common mistake when sending FormData via fetch() is manually adding a Content-Type header:

// ❌ WRONG: THIS DESTROYS YOUR REQUEST
fetch('/api/upload', {
  method: 'POST',
  headers: {
    'Content-Type': 'multipart/form-data' // DO NOT DO THIS!
  },
  body: formData
});

+-------------------------------------------------------------------------------+
|                    WHY MANUAL Content-Type BREAKS MULTIPART                   |
|                                                                               |
|  WHAT THE SERVER NEEDS:                                                       |
|  Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu|
|                                                                               |
|  WHAT HAPPENS WHEN YOU MANUALLY SET THE HEADER:                               |
|  Content-Type: multipart/form-data                                            |
|  (The critical boundary parameter is STRIPPED! The server cannot parse parts!)|
|                                                                               |
|  CORRECT USAGE (Let browser set headers automatically):                      |
|  fetch('/api/upload', { method: 'POST', body: formData });                   |
+-------------------------------------------------------------------------------+

When you pass a FormData instance as the body, the browser automatically computes the exact multipart boundary delimiter and sets the header: Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryXyZ123....

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 77–81 (const formData = new FormData(form);): Harvests all named input elements automatically from the HTML form.
• Line 84–85 (formData.append(...)): Injects extra programmatic metadata (timestamp and screen resolution) before submission.
• Line 90 (for (const [key, value] of formData.entries())): Uses modern ES6 iterator destructuring to traverse all key-value entries in the payload.
• Line 92 (value instanceof File): Distinguishes between textual string inputs and binary File objects.
• Line 99–104: Renders the inspected keys, value types, and file metadata into an interactive inspection table.

Expected Browser Render Output

+-------------------------------------------------------------+
| User Profile Form                                           |
| Username: [ alex_rivera ]                                   |
| Team Role: [ Software Engineer ▾ ]                          |
| Avatar Image: [ Choose File ] avatar.png                    |
| [ Inspect FormData Payload ]                                |
|                                                             |
| FormData Serialized Key-Value Entries:                      |
| +───────────────────+─────────────+───────────────────────+ |
| | Key (Name)        | Type        | Value / Metadata      | |
| +───────────────────+─────────────+───────────────────────+ |
| | username          | String      | alex_rivera           | |
| | role              | String      | developer             | |
| | avatar_file       | File Object | Name: avatar.png, ... | |
| | client_timestamp  | String      | 2026-08-21T02:15:00Z  | |
| | screen_resolution | String      | 1920x1080             | |
| +───────────────────+─────────────+───────────────────────+ |
+-------------------------------------------------------------+