json-form-data

json-form-data

A library to convert JavasScript objects into form data.

Features

• Supports CommonJS and AMD module loaders
• Converts nested objects and arrays
• Compatible with legacy web browsers
• Supports all primitive data types
• Converts Date objects to ISO strings
• Supports File and FileList data types
• Skips null and undefined values
• Custom value mappings
• Good unit test coverage

Overview

This library converts a JSON object into form data, allowing files and primitive data to be sent to a server in a single HTTP request.

Single Page Web Applications (SPA's) primarily use JSON formatted payloads. This causes problems when you need to send a file along with additional data, as files cannot be sent to a server in a JSON formatted payload.

This library addresses the limitations of similar libraries by allowing conversion of deeply nested JSON objects, better unit test coverage and exclusion of null and undefined values from the resulting form data.

A custom mapping function allows JSON values to be transformed before they are appended to form data. You can use this to provide your server side with the values it expects.

Usage

Input as JSON

var testObject = {
    prop1: 'test',
    prop2: 2,
    prop3: null,
    prop4: undefined,
    prop5: true,
    prop6: false,
    prop7: new File(['file content'], 'my_file.txt'),
    prop8: new Date('05 January 2020 16:52:00 GMT'),
    prop9: {
        prop1: 'test',
        prop2: 2,
        prop3: null,
        prop4: undefined,
        prop5: true,
        prop6: false,
        prop7: [
            'test', 
            2, 
            null, 
            undefined, 
            true, 
            false
        ]
    }
};

var options = {
    showLeafArrayIndexes: true,
    includeNullValues: false,
    mapping: function(value) {
        if (typeof value === 'boolean') {
            return +value ? '1': '0';
        }
        return value;
    }
};

var formData = window.jsonToFormData(testObject, options);

Output as multipart/formdata

prop1
test

prop2
2

prop5
1

prop6
0

prop7
Content-Disposition: form-data; name="My File"; filename="my_file.txt"
Content-Type: text/plain

prop8
2020-01-05T16:52:00.000Z

prop9[prop1]
test

prop9[prop2]
2

prop9[prop5]
1

prop9[prop6]
0

prop9[prop7][0]
test

prop9[prop7][1]
2

prop9[prop7][2]
1

prop9[prop7][3]
0

Options

Option	Default	Description
showLeafArrayIndexes	true	Shows indexes for items in array leaf nodes.
includeNullValues	false	Includes null values in the form data.
mapping	x => y	Overrides the default value mappings true => '1' and false => '0'.

CDN

json-form-data is also available via a CDN. Just include the following script tag in your page.

<script src="https://unpkg.com/json-form-data@^1.6.0/dist/jsonToFormData.min.js" />

Browser Support

IE / Edge	Firefox	Chrome	Safari
IE10, IE11, Edge	latest	latest	latest

Contributors

• hyperatom
• illiatdesdindes
• superhawk610

Sponsors

We use BrowserStack to automate our regression tests to ensure compatibility with supported browsers.