react-file-uploader is a set of highly customizable React components that helps you to build a file uploader in your application easily.
react-file-uploader is not production ready because it is not fully tested on all browsers, and the unit test coverage is just not good enough. However, it has been used in my cms project since v0.3.0.
To install:
npm install --save react-file-uploader
this module currently contains 4 major entities, which are
- Receiver
- UploadManager
- UploadHandler
- File Status
Receiver
helps you to manage the Drag and Drop functionality. Once you mounted the Receiver
component, your application will start listen to dragenter
, dragover
, dragleave
and drop
events.
import { Receiver } from 'react-file-uploader';
<Receiver
customClass={STRING_OR_ARRAY}
style={OBJECT}
isOpen={BOOLEAN}
onDragEnter={FUNCTION}
onDragOver={FUNCTION}
onDragLeave={FUNCTION}
onFileDrop={FUNCTION}
>
<div>
visual layer of the receiver (drag & drop panel)
</div>
</Receiver>
- customClass -
string | array
: the class name(s) for thediv
wrapper - style -
object
: the style for thediv
wrapper - isOpen -
boolean
required
: to control in the parent component whether the Receiver is visble. - onDragEnter -
function
required
: whenisOpen
isfalse
, this will be fired with the window event ofdragenter
once .
You may make use of the drag & drop event callbacks.
// @param e Object DragEvent
function onDragEnter(e) {
this.setState({ isReceiverOpen: true });
}
- onDragOver -
function
: this will be fired with the window event ofdragover
.
// @param e Object DragEvent
function onDragOver(e) {
// your codes here
}
- onDragLeave -
function
required
: when the drag event entirely left the client (i.e.dragLevel === 0
), this will be fired with the window event ofdragleave
once.
// @param e Object DragEvent
function onDragLeave(e) {
this.setState({ isReceiverOpen: false });
}
- onFileDrop -
function
required
: this will be fired with the window event ofdrop
. You may execute any validation / checking process here i.e. size, file type, etc.
// @param e Object DragEvent
// @param files Array the files dropped on the target node
function onFileDrop(e, files) {
// check if the files are drop on the targeted DOM
const node = ReactDOM.findDOMNode(this.refs.uploadPanel);
if (e.target !== node) {
return;
}
files.forEach(file => {
// check file size
if (file.size > 1000 * 1000) {
file.error = 'file size exceeded 1MB';
}
})
// put files into state/stores by setState/action
this.setState({
files: this.state.files.concat(files),
});
// close the Receiver after file dropped
this.setState({ isReceiverOpen: false });
}
Upload Manager serves as a high order component which helps you to manage the upload related parameters and functions. It prepares the upload function with superagent
the children elements, and helps you to update the lifecycle status of the uploading files.
**IMPORTANT: this high order component serves only for ** UploadHandler
import { UploadManager } from 'react-file-uploader';
<UploadManager
customClass={STRING_OR_ARRAY}
style={OBJECT}
uploadUrl={STRING}
uploadHeader={OBJECT}
onUpload={FUNCTION}
onUploadProgress={FUNCTION}
onUploadEnd={FUNCTION}
>
// UploadHandler as children
files.map(file => (
<UploadHandle key={file._id} file={FILE_INSTANCE} autoStart={BOOLEAN} />
))
</UploadManager>
- component -
string
: the DOM tag name of the wrapper - customClass -
string | array
: the class name(s) for the wrapper - style -
object
: the style for the wrapper - uploadUrl -
string
required
: the url of the upload end point from your server. - uploadHeader -
object
: the header object to be set as request header. - onUploadStart -
function
: this will be fired when thePOST
request is just sent.
// @param file Object the file object returned with UPLOADING status and 0% progress.
function onUploadStart(file) {
// your codes here
}
- onUploadProgress -
function
: this will be fired when thePOST
request returns progress. A debounced function is STRONGLY recommaned to prevent from performance issue.
// @param file Object the file object returned with UPLOADING status and n% progress.
function onUploadProgress(file) {
// your codes here
}
- onUploadEnd -
function
required
: this will be fired upon the end ofPOST
request.
// @param file Object the file object returned with either UPLOADED or FAILED status and 100% progress. When it is wilh FAILED status, error property should be also assigned to the file object.
function onUploadEnd(file) {
// your codes here
}
- errorHandler -
function
: this function is to process the arguments of(err, res)
insuperagent.end()
. In this function, you can resolve the error and result according to your upload api response. Default implementation is available as defaultProps.
function errorHandler(err, res) {
let error = null;
const body = clone(res.body);
if (err) {
error = err;
} else if (body && body.errors) {
error = body.errors;
}
delete body.errors;
return { error, result: body };
}
Upload Handler helps you to execute the upload lifecycle, which is start
, progress
and end
. It also acts as the presentation layer of a file, showing users the info of the uploading / uploaded file.
import { UploadHandler } from 'react-file-uploader';
<UploadHandler
customClass={CLASS_STRING_OR_ARRAY}
style={STYLE_OBJECT}
file={FILE_OBJECT}
autoStart={BOOLEAN}
upload={UPLOAD_FUNCTION}
/>
component
-string
: the DOM tag name of the wrappercustomClass
-string | array
: the class name(s) for the wrapperstyle
-object
: the style for the wrapperfile
-object
required
: the file object that is uploaded / going to be uploaded.autoStart
-boolean
: whenautoStart
is set totrue
, upon the UploadHandler component did mount, it will detect if the file i.e. as props is with thePENDING
status and initialise aPOST
request which is sent to theuploadUrl
you passed to theUploadManager
.upload
-function
: the function that contains the upload logic, you may pass it directly when you are usingUploadHandler
alone, or it could be prepared byUploadManager
.
// @param url String API upload end point
// @param file Object File Object
function upload(url, file) {
// your codes here
}
react-file-uploader
defines a set of status constants to represent the file status. The corresponding status will be assign to a file object throughout the uploading life cycle.
FAILED = -1
PENDING = 0
UPLOADING = 1
UPLOADED = 2
- complete test cases
- add real-world example
- support optional data, i.e. custom image name and destination
MIT