A new way to file-upload in React
File uploading from the browser isn’t new. It’s been with us for a long time now. There are also plenty of projects and libraries aiming to help web applications that require this kind of functionality. Yet, there aren’t many that encompass all you need in one place.
If you’re building a React app that needs to upload files from the browser, look no further.
What I’m referring to is a project I’ve been working on for a few months now. Little by little I got it to a point that I now (proudly) feel is ready to be shared.
So, without further ado, I give you:
What is it?
Modern file-upload components & hooks for React.
What does it do?
Anything your heart desires! As long as your heart desires to upload files from the browser.
More precisely: React-Uploady enables you to build (client-side) file-upload features with just a few lines of code. RU provides the foundations needed to upload files from the browser — The rest is up to you.
Technically, RU is a monorepo with several packages. Each provides different capabilities which can be used separately or combined into an all encompassing solution. It’s the Mega Tigerzord (which my kids assure me is TOTALLY AWESOME) of open source libraries!
Setting out to build this library I had the following goals in mind:
a) It should be simple to use
b) It should be configurable and extensible
c) It should be small
d) It should provide all necessary features related to file-uploading
Now, this list may seem self-contradictory, but I’d like to show you that it’s really not.
🟢 Let’s talk simple
That’s literally all the code needed to get a working upload button that lets your users choose a file (or files) from their system and have them uploaded to your server.
It doesn’t get much simpler than that!
🟢 Let’s talk configurable and extensible.
Just about everything in RU is configurable and can be changed. You can add parameters and headers to be sent along the uploaded file. You can control (filter) what kind of files get uploaded. All of this you can do upfront when you’re declaring the Uploady components. You can also add and change settings dynamically based on the content being uploaded.
It would be impossible to cover all of the options in this article so in future posts I will share more advanced examples and usage.
In the meantime, the GH guides section includes several advanced use-cases. And so does RU’s storybook.
🟢 Let’s talk small
The entire library (all packages combined) is just ~16KB minified & gzipped (without polyfills). The core packages with the context provider (@rpldy/uploady) is just ~12KB minified & gzipped.
🟢 Let’s talk FEATURES
RU brings a lot of file-upload related power — you can do chunked uploads and enable retries for failed requests. It supports concurrent uploads and grouping files into a single request.
Events are triggered throughout the life-cycle of the upload so progress can be easily shown as well as being able to cancel uploads either manually (by the user) or programmatically.
Most of these features are implemented in hooks so it’s trivial to integrate into a React application. If hooks not your style (or just not in your React version), Uploady provides an imperative API as well.
Beyond the core uploading mechanism and the Uploady context provider, RU provides several useful components such as: upload-button, upload-drop-zone & upload-preview to name a few.
Covering all of the features here will also take a while so I’ll expand on these in future posts.
Getting Started
The best place to get started is React-Uploady’s Github page. There you’ll find details about the different packages alongside deeper explanations and guides.
Give me code!
To emphasize how easy it is to get started, here’s an example using React-Uploady and rc-progress to display upload progress:
First, we import the stuff we need:
import React, { useState } from "react";
import { Circle } from "rc-progress";
import Uploady, { useItemProgressListener } from "@rpldy/uploady";
import UploadButton from "@rpldy/upload-button";We’ll use the Circle progress bar from rc-progress and UploadButton component, and useItemProgressListener hook from RU.
const UploadProgress = () => {
const [progress, setProgess] = useState(0);
const progressData = useItemProgressListener(); if (progressData && progressData.completed > progress) {
setProgess(() => progressData.completed);
} return progressData && <Circle style={{ height: "100px" }}
strokeWidth={2}
strokeColor={progress === 100 ? "#00a626" : "#2db7f5"}
percent={progress} />;};
To show progress we get the information from the useItemProgressListener hook which provides among other things the completed percentage. We plug that into the Circle component and voila.
const App = () => <Uploady
destination={{ url: "http://sample-server.comm" }}>
<UploadButton />
<SampleProgress />
</Uploady>;We wrap our app (or the section where uploads take place) with <Uploady>, which is the context provider and where we typically declare our upload options. For example, the destination prop with the server endpoint (url).
Simple Right? We have file upload with progress bar. It looks something like this:
The code sample is available in this sandbox:
Note: This example shows progress for a single file upload. Example of multiple file progress can be found in the guides.
I Hope this article made you want to give React-Uploady a try.
I’m looking forward to hearing your thoughts and suggestions on how it can be improved and grown.
And of course appreciate a ⭐ on GH if you don’t mind… :)
