Author avatar

Manujith Pallewatte

Asynchronous File Upload in React

Manujith Pallewatte

  • Aug 9, 2019
  • 9 Min read
  • Aug 9, 2019
  • 9 Min read
Web Development


Uploading files is a common requirement for a real-world application. More likely, it is a minor functionality than a core component of your app. So we tend to overlook the importance of proper engineering of it. A lazy file uploader and file server are a guaranteed headache for the future. At this very moment, I'm working on reimplementing a similarly poor implementation amidst a massive component structure. So, in this guide, I'll explore file upload best practices along with the front-end side of it.

Let's take a look at the following scenario: We have a simple form in our app which consists of a text input, file upload, and a text area. The app we are building should be able to asynchronously submit the form data to a REST API. First, we'll outline the basic App component along with the pre-requisites for submitting data to the API. My goto HTTP client for React is axios, but you could go with fetch as well. Initialize the front-end with the following commands and modify the App.js to include our uploader boilerplate. The source is available in the Github repo if you want to take a quick look.

1$ create-react-app uploader
2$ cd uploader
3$ npm install --save axios
1// App.js
3import React, { useState } from 'react';
4import logo from './logo.svg';
5import './App.css';
6import axios from 'axios';
8const API_BASE = "http://localhost:5000"
10function submitForm(contentType, data, setResponse) {
11 axios({
12 url: `${API_BASE}/upload`,
13 method: 'POST',
14 data: data,
15 headers: {
16 'Content-Type': contentType
17 }
18 }).then((response) => {
19 setResponse(;
20 }).catch((error) => {
21 setResponse("error");
22 })
25function App() {
26 const [title, setTitle] = useState("");
27 const [file, setFile] = useState(null);
28 const [desc, setDesc] = useState("");
30 function uploadWithFormData(){
32 }
34 function uploadWithJSON(){
36 }
38 return (
39 <div className="App">
40 <h2>Upload Form</h2>
41 <form>
42 <label>
43 File Title
44 <input type="text" vaue={title} 
45 onChange={(e) => { setTitle( )}} 
46 placeholder="Give a title to your upload" />
47 </label>
49 <label>
50 File
51 <input type="file" name="file" onChange={(e) => setFile([0])} />
52 </label>
54 <label>
55 Description
56 <textarea value={desc} onChange={(e) => setDesc(}></textarea>
57 </label>
59 <input type="button" value="Upload as Form" onClick={uploadWithFormData} />
60 <input type="button" value="Upload as JSON" onClick={uploadWithJSON}/>
61 </form>
62 </div>
63 );
66export default App;

The File Server

In most cases, having a file server is only a minor concern for your application. So we tend to implement it lazily, without giving proper thought to the consequences. Since the purpose of the guide is not to focus on the backend aspects of file servers, I'll only highlight a few useful pointers.

  1. Make sure your file uploading functionality doesn't block the rest of the application.
  1. Using a separate server backend to handle file uploading may help with scaling in a later stage. Node.Js file upload is the go-to practice around here.
  1. Be aware of the bandwidth requirements in serving files from your server instance. If your files are larger in size, using a CDN service would be efficient.
  1. Check if your platform provider has an object store service - AWS, GCloud, DigitalOCean each has its own object storage provider. Utilizing these services provide additional benefits, including high availability on files and saving on server bandwidth.

Getting back to the topic, for this guide I compiled a simple node.js file server. The source is available in the Github Repo. This server backend exposes a REST API with two endpoints:

  1. /hello will simply display the infamous Hello world! message.
  1. /upload will accept key-value either as JSON data or as form data.

Since the upload endpoint supports both content types, we can use it to test the different methods of facilitating file uploads from the front-end. Now we can explore the different upload mechanisms to use with React.

Upload with FormData

As in any Single Page Application (SPA), in React we tend to interact with our server through a REST endpoint. So we end up having our entire messaging structure based on a common data format, which is JSON in almost all cases. But, once we come to a point where we need to implement a file upload, we quickly realize that JSON might not be the default candidate for the job. Usually, files are sent to servers as Multi-part Form Data. The way it behaves removes the unnecessary complexities of chunking and streaming large files from the front-end developer. While it lacks control, it is still the preferred way for uploads if the whole application is not based on the functionality of the file upload. So, let's first figure out how we can send the file as form data.

Lucky for us, Javascript API comes with a FormData API to build forms on the fly. In the below code, we complete the file upload process using form data.

1 function uploadWithFormData(){
2 const formData = new FormData();
3 formData.append("title", title);
4 formData.append("file", file);
5 formData.append("desc", desc);
7 submitForm("multipart/form-data", formData, (msg) => console.log(msg));
8 }

The code is quite simple. We first create an instance of FormData and then append the fields to it. The only thing to remember is that the field name for file should match the corresponding field name in the server-side. Once you plug this and test, you should see a file created in the server's folder and a console displaying the message, "OKAY".


  1. The file upload mechanism is quite simple and the browser API handles the complexities of the upload.

    Note that this still is NOT a proper streaming solution since the whole file is transmitted in one POST request. For very large files, a custom slice-and-upload mechanism needs to be implemented.

  2. Many external APIs will be able to default support it. For example, if you are using a third party file storage service, their API would support using the above-method without any tweaks.


If you already have a well defined JSON API, having to process form data is cumbersome. First, you need to make sure the server supports it; then, you need to make changes in the front-end to convert your data dictionaries to form data before submitting. So, in the next section, we'll explore how we can upload for an existing JSON-based API.

Uploading with JSON

If we are to upload with JSON, the only requirement is that the file should be converted to a string, somehow. If we can represent the file as a string, we can transmit it within a JSON body as well. There are few different string representations to a blob (or a binary object). We will be using Base64 encoding, for our use case. Base64 essentially converts a binary array to an ASCII string format. In the following code, we implement this.

1 async function uploadWithJSON(){
2 const toBase64 = file => new Promise((resolve, reject) => {
3 const reader = new FileReader();
4 reader.readAsDataURL(file);
5 reader.onload = () => resolve(reader.result);
6 reader.onerror = error => reject(error);
7 });
9 const data = {
10 title: title,
11 file: await toBase64(file),
12 desc: desc
13 }
15 submitForm("application/json", data, (msg) => console.log(msg));
16 }

We use the FileReader class to convert our file to Base64 and submit it to the server just like a normal JSON message.


The key advantage of this method is the possibility of using the same JSON API without major changes to both the backend and frontend. As I stated above though, I would only recommend this for files of smaller sizes. For example, this is ideal for a profile avatar upload, where the input image is processed and only low-quality, cropped images are saved in the backend.


In this guide, we explored the different methods of implementing asynchronous file uploading in React. First, we looked at a FormData-based approach where we simulate an HTML form request and send it using Axios. Then, we observed how we can use Base64 encoding to provide file upload functionality without making changes to an existing API. An important take away is to know that each approach has its benefits and pitfalls. If your application needs file upload at some point, I suggest keeping that in mind in the initial designs. It could potentially save you days of work, at a later stage.