FormData: The Right Way to Upload Files

Why it exists

HTTP requests are fundamentally text-based, but files are binary. Sending a file requires a special format to tell the server where the text data ends and the binary file data begins. The multipart/form-data encoding solves this, and the FormData interface is the standard JavaScript API for building that payload without messy, error-prone string manipulation.

The mental model

Imagine you're mailing a package with several items and a letter. You can't just throw them all in a box. You need to label each item and separate them with dividers. FormData is the API that acts as your packer, creating a multipart/form-data payload where each key/value pair is a separate, labeled "part" in the request body. This allows a server to easily parse mixed content like text fields and files.

How it works

You create a new FormData() object. Then, you use the .append(key, value) method to add data. The value can be a string for a text field or a special object for a file. In React Native, a file is typically represented as { uri: file.uri, type: 'image/jpeg', name: 'photo.jpg' }. When you pass this FormData object as the body of a fetch request, the runtime automatically serializes it into the correct multipart/form-data format and, crucially, sets the Content-Type header with a unique boundary identifier.

When to use it

Use FormData whenever you need to send a file (image, video, PDF, etc.) from your app to a server. It is the standard for any "file upload" feature. It's also the correct tool for submitting complex forms that mix text inputs and files in a single request.

When not to use it

For API calls that only send structured data like strings and numbers, stick with a plain JavaScript object, JSON.stringify it, and set the Content-Type header to application/json. Using FormData for simple JSON data is inefficient overkill; its purpose is to handle multipart bodies.

One canonical example

To upload a photo in React Native after getting it from an image picker:

const data = new FormData();
data.append('userId', '123');
data.append('photo', {
uri: image.uri,
name: 'profile.jpg',
type: 'image/jpeg',
});

fetch('https://api.example.com/upload', {
method: 'POST',
body: data,
});

Notice no Content-Type header is set manually. This is the correct and required approach.