React-Uploady

Modern file uploading - components & hooks for React

File uploadReact
rpldy/react-uploadyreact-uploady.org/@rpldy/uploady

README

React Uploady Logo
React Uploady Logo

Modern file-upload components & hooks for React.

npm version circleci status codecov status rpldy storybook lerna MIT License

Contents
    
Intro
Documentation
Installation
Packages
Examples
Important Concepts
Resumable Uploads
UMD Bundles
Contribute
Acknowledgements

Intro


    React-Uploady is a lightweight library - enabling you to build (client-side) file-upload features with just a few lines of code.
    Uploady provides the foundations needed to upload files from the browser - The rest is up to you.


React-Uploady Demo

The philosophy behind this library is that it should be as simple as possible to use, yet customizable at every point.
You can start simple, or you can configure just about every aspect of the upload flow.
For this purpose, there are components, hooks, and plenty of features.
You get to choose which ones you need and only install the dependencies required (See Packages details below)

React-Uploady has a small footprint (by design) with very few (and small) dependencies.

BundleMinifiedGZipped
|-----------------------------|---------------|--------------|
core28.6KB10.0KB
core39.8KB13.0KB
core49.1KB15.3KB
everything75.7KB22.1KB

Documentation


Getting Started


The best place to get started is at our: React-Uploady Documentation Website

Another great place to learn about React-Uploady is our video series on Youtube.

Changelog


For a list of versions and changes, see the CHANGELOG

Discussions


Please check the discussions area here in Github. If you have a question about use-cases or flows you'd like to achieve with Uploady, discussions is the place to look for existing answers or add your own.

If you're using Uploady in Production, please drop a comment here. It's always great to hear how people and companies use it.

Installation


React-uploady is a mono-repo, and as such provides multiple packages with different functionality.

For React applications, at the very least, you will need the Uploady provider:

  1. ``` sh
  2. #Yarn:
  3.    $ yarn add @rpldy/uploady

  5. #NPM:
  6.    $ npm i @rpldy/uploady
  7. ```

If you wish to use the uploading mechanism (no UI), at the very least, you will need the Uploader:

  1. ``` sh
  2. #Yarn:
  3.   $ yarn add @rpldy/uploader

  5. #NPM:
  6.   $ npm i @rpldy/uploader
  7. ```

After that, you can add additional packages as needed. See below for more details.

Packages


Main Packages

@rpldy/uploader - The processing and queuing engine
@rpldy/uploady - The context provider for react-uploady and hooks (lots of hooks)

UI Packages

@rpldy/upload-button - Upload button component and asUploadButton HOC
@rpldy/upload-preview - Image&video preview component for files being uploaded
@rpldy/upload-url-input - Input component to send URL as upload info (ex: Cloudinary)
@rpldy/upload-drop-zone - (Drag&)Drop zone to upload files and folder content
@rpldy/upload-paste - Easily add paste-to-upload to React components
@rpldy/retry-hooks - Hooks to interact with the retry mechanism

Providers

@rpldy/chunked-uploady - Wrapper for Uploady with support for chunked uploads
@rpldy/tus-uploady - Wrapper for Uploady with support for tus(resumable) uploads
@rpldy/native-uploady - Uploady for React Native (no react-dom)

Senders

@rpldy/sender - Uploady's main file sender (XHR)
@rpldy/chunked-sender - add chunked uploads support on top of the XHR Sender
@rpldy/tus-sender - add TUS resumable upload support
@rpldy/mock-sender - use Mock sender for testing purposes

Extras

@rpldy/retry - Add support for retrying failed uploads

Internal Packages

@rpldy/shared - Internal set of utils+types that all packages require
@rpldy/shared-ui - Internal set of utils+types that all UI packages require
@rpldy/life-events - providescancellable pub/sub "events"
@rpldy/safe-storage - safe (don't throw) versions of local and session storage
@rpldy/simple-state - deep proxy object, so it's only updateable through an update method

Examples


For specific usage, see documentation in the relevant package README file.

For upload options, see the @rpldy/uploady docs.

Simple Upload Button


This example shows how you add Uploady and UploadButton to your app.
This is all it takes to get file uploading to work in your React application.

  1. ``` js

  3. import React from "react";
  4. import Uploady from "@rpldy/uploady";
  5. import UploadButton from "@rpldy/upload-button";

  7. const App = () => (<Uploady
  8.     destination={{ url: "https://my-server/upload" }}>
  9.     <UploadButton/>
  10. </Uploady>);

  12. ```

Custom Upload Button


In case you want to use your own component as the upload trigger, use the asUploadButton HOC:

  1. ``` js

  3. import React from "react";
  4. import Uploady from "@rpldy/uploady";
  5. import { asUploadButton } from "@rpldy/upload-button";

  7. const DivUploadButton = asUploadButton((props) => {
  8.     return <div {...props} style={{ cursor: "pointer" }}>
  9.         DIV Upload Button
  10.     </div>
  11. });

  13. const App = () => (<Uploady
  14.     destination={{ url: "https://my-server/upload" }}>
  15.     <DivUploadButton/>
  16. </Uploady>);

  18. ```

Progress Hook


  1. ``` js

  3. import React from "react";
  4. import Uploady, { useItemProgressListener } from "@rpldy/uploady";
  5. import UploadButton from "@rpldy/upload-button";

  7. //must be rendered inside
  8. const LogProgress = () => {
  9.     useItemProgressListener((item) => {
  10.         console.log(`>>>>> (hook) File ${item.file.name} completed: ${item.completed}`);
  11.     });

  13.     return null;
  14. }

  16. const App = () => (<Uploady
  17.     destination={{ url: "https://my-server/upload" }}>
  18.     <LogProgress/>  
  19.     <UploadButton/>
  20. </Uploady>);

  22. ```

Add support for resumable(tus) uploads


  1. ``` js
  2. import React from "react";
  3. import TusUploady from "@rpldy/tus-uploady";
  4. import UploadButton from "@rpldy/upload-button";
  6. const App = () => (<TusUploady
  7.      destination={{ url: "https://my-tus-server/upload" }}
  8.      chunkSize={2142880}
  9.      sendDataOnCreate>
  10.      <UploadButton/>
  11. </TusUploady>);
  12. ```

Add support for chunked uploads


Can be used with servers that support chunked uploads

  1. ``` js
  2. import React from "react";
  3. import ChunkedUploady from "@rpldy/chunked-uploady";
  4. import UploadButton from "@rpldy/upload-button";

  6. const App = () => (<ChunkedUploady
  7.     destination={{ url: "https://my-server/upload" }}
  8.     chunkSize={5242880}>
  9.       
  10.     <UploadButton/>
  11. </ChunkedUploady>);

  13. ```

See more (advanced) examples in our guides and storybook.


Important Concepts


Upload Options


These are the options that are passed to the uploader to configure aspects of the upload process.
For example, whether files can be grouped in a single request (by default, no).

Upload Options are typically passed to the Uploady instance. But these can be overridden. For example, by props passed to the upload button.
Or even during upload processing.

Destination


Passed as a part of the upload options. It's an object that is used to configure the end-point where the files will be uploaded to.
Its type is defined here.

See more information in the Uploady README.

At the very least, a destination should contain a URL property with the server endpoint.

Enhancer


  1. ``` js

  3. (uploader: UploaderType, trigger: Trigger<mixed>) => UploaderType
  4. ```

Enhancers are functions that can enhance an uploader instance. They are also passed as part of the options given to the Uploady instance.

As they are applied when the uploader instance is created, they can change the way uploader does things or pass different defaults.

See this guide for practical information and sample code.

Batch


When a file or files are handed over to the uploader, they are grouped into a batch.
This batch will have its own lifetime events.
With a batch ID, it is possible to cancel all files that are part of it. It can also be used to retry all files in the batch (see @rpldy/retry).

BatchItem


Each file (or URL) added to the uploader is wrapped by a BatchItem object. They will have a unique ID within the life-time of the uploader instance.
A BatchItem has its own lifetime events.

Resumable Uploads


Uploady supports resumable uploads through the tus protocol.
Instead of using from @rpldy/uploady, use from @rpldy/tus-uploady and you will have resumable upload support on the client side.
Your server will also have to support the same protocol for this to work, of course.

See the @rpldy/tus-uploady documentation for more details.

UMD Bundles


React-uploady is also available on CDNs such as unpkg.com and jsdelivr.com

See this guide for more information on how to use.

jsDelivr


BundleURL
----------------------------|------------------------------------------------------------------------------------------|
corehttps://cdn.jsdelivr.net/npm/@rpldy/uploader/umd/rpldy-core.umd.min.js
corehttps://cdn.jsdelivr.net/npm/@rpldy/uploady/umd/rpldy-ui-core.umd.min.js
corehttps://cdn.jsdelivr.net/npm/@rpldy/chunked-uploady/umd/rpldy-ui-core-chunked.umd.min.js
everythinghttps://cdn.jsdelivr.net/npm/@rpldy/uploady/umd/rpldy-all.umd.min.js

You will most likely need the polyfill (core js) bundle as well (load it first):

- core bundles -> https://cdn.jsdelivr.net/npm/@rpldy/uploady/umd/polyfills-bundle.js
- everything bundle -> https://cdn.jsdelivr.net/npm/@rpldy/uploady/umd/polyfills-all-bundle.js

unpkg


BundleURL
----------------------------|-------------------------------------------------------------------------------|
corehttps://unpkg.com/@rpldy/uploader/umd/rpldy-core.umd.min.js
corehttps://unpkg.com/@rpldy/uploady/umd/rpldy-ui-core.umd.min.js
corehttps://unpkg.com/@rpldy/chunked-uploady/umd/rpldy-ui-core-chunked.umd.min.js
everythinghttps://unpkg.com/@rpldy/uploady/umd/rpldy-all.umd.min.js

You will most likely need the polyfill (core js) bundle as well (load it first):

- core bundles -> https://unpkg.com/@rpldy/uploady/umd/polyfills-bundle.js
- everything bundle -> https://unpkg.com/@rpldy/uploady/umd/polyfills-all-bundle.js

Note that unpkg does a redirect to the latest version in case the URL doesn't already contain it. So don't copy any of the URLs above into your code.

Instead, load them in the browser first and then copy the final URL from there (after the redirect).


Contribute


Show Uploady your support by giving us a ⭐.

If you'd like to help Uploady grow & improve, take a look at the Contributing doc.

The Discussions page is a great place to ask questions, raise ideas and interact with Uploady maintainer, users and contributors.

Already using Uploady in Production? Let us know how & where in this open discussion.

Financial Contributors


Companies/Organizations that have contributed to the project:


Support us


Want to help sustain and grow Uploady? You can become a financial backer on OpenCollective.

Become a financial contributor and help us sustain our community.

You can make a one-time contribution or on a monthly basis



Acknowledgements


logo's wing thanks to Illustration Vectors by Vecteezy