How Form Data Works

Before we look at the code, let’s understand what “form data” means at the HTTP level. When you fill out a form on a website and hit submit, the browser needs to pack up your inputs and send them to the server. There are two standard ways to do this, and they differ in how the data is encoded in the request body.

URL-Encoded Form Data

The simplest format is URL-encoded form data, also known by its content type: application/x-www-form-urlencoded. It encodes key-value pairs the same way URL query parameters work: keys and values are joined with =, pairs are separated by &, and special characters are percent-encoded.

For example, a login form with a username and password gets encoded as:

1
username=emilys&password=emilys%20pass

The Content-Type header is set to application/x-www-form-urlencoded. This format is compact and simple, but it only supports flat text values. You can’t send files or binary data with it.

Multipart Form Data

The second format is multipart form data, also known by its content type: multipart/form-data. It’s designed for more complex payloads, particularly ones that include files alongside regular text fields.

Instead of encoding everything into a single string, multipart form data splits the body into separate parts, each with its own headers and content. A boundary string separates the parts. It looks something like this under the hood:

1
--boundary123
2
Content-Disposition: form-data; name="username"
3

4
emilys
5
--boundary123
6
Content-Disposition: form-data; name="avatar"; filename="photo.png"
7
Content-Type: image/png
8

9
<binary file data>
10
--boundary123--

Each part has a name, and file parts include a filename and their own content type. This is how browsers send file uploads. The <input type="file"> element always triggers multipart encoding.

In modern JavaScript applications, you work with multipart data through the FormData API, which is available in both browsers and Node.js (v18+). You’ll rarely construct the raw multipart body yourself.

Which One to Use?

Use URL-encoded (bodyUrlParams) for simple key-value data. Login forms, search queries, filter parameters. It’s the lightest option when you’re only sending text.

Use multipart (bodyFormData) when you need to send files, or when the API explicitly expects multipart/form-data.