lite-uploader

LiteUploader

Examples | Changelog
This is a lightweight library for NodeJS and jQuery, aiming to make uploading files a doddle. With some useful options including basic validation, it is a good choice for any developer who is not so worried about supporting legacy browsers.

Features

• dependency free
• file type and size validation
• support for custom validators
• hooks for all major events like progress, success, fail etc
• drag/drop support
• ability dynamically update the form data packet before each upload
• upload multiple files as individual requests

NodeJS

npm install lite-uploader --save

Browser

<script src="./src/liteuploader.js"></script>
jQuery is supported but is optional

Options

<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>

<td>url</td>
<td>String or Function (required)</td>
<td>null</td>
<td>url that will handle the upload, or a function that resolves with the url</td>

<td>ref</td>
<td>String (required)</td>
<td>null</td>
<td>the request argument name for the file form data. Will fallback to the name property of the file input field if not supplied.</td>

<td>method</td>
<td>String</td>
<td>POST</td>
<td>allows overriding of the default HTTP request method if necessary</td>

<td>rules</td>
<td>Object</td>
<td>{}</td>
<td>object where you can specify validation rules for the files to be uploaded - current supported rules are:
  <ul>
    <li>allowedFileTypes (list of comma-separated mime-types, wildcards such as image/* are also supported)</li>
    <li>maxSize (in bytes)</li>
  </ul>
</td>

<td>params</td>
<td>Object</td>
<td>{}</td>
<td>object of params to be sent to the server in addition to the files being uploaded</td>

<td>headers</td>
<td>Object</td>
<td>{}</td>
<td>object of headers to be sent to the server</td>

<td>validators</td>
<td>Array</td>
<td>[]</td>
<td>an array of functions that can take a File and return a validation result on it, see examples for usage</td>

<td>singleFileUploads</td>
<td>Boolean</td>
<td>false</td>
<td>set to true to upload each file of a selection using an individual request</td>

<td>withCredentials</td>
<td>Boolean</td>
<td>false</td>
<td>indicates whether requests should be made using credentials such as cookies</td>

<td>beforeRequest</td>
<td>Function</td>
<td>null</td>
<td>delay the file upload request by returning a promise. Recieves the Files and the FormData. Expected to resolve with the FormData to continue. Reject to stop upload.</td>

<td>sendAsFormData</td>
<td>Boolean</td>
<td>true</td>
<td>when set to false and singleFileUploads is true, dont send the file payload as form data. Also any params added via 'addParam' to form data, will be ignored</td>

Events

<th>Name</th>
<th>Parameters</th>
<th>Description</th>

<td>lu:errors</td>
<td>eventName, {errors}</td>
<td>triggered when errors are found, including built-in and custom validators - see 'Error Types' section for more</td>

<td>lu:start</td>
<td>eventName, {files}</td>
<td>triggered before any uploading starts</td>

<td>lu:finish</td>
<td>eventName</td>
<td>triggered when all uploading has finished</td>

<td>lu:before</td>
<td>eventName, {files}</td>
<td>triggered before each request to the server</td>

<td>lu:progress</td>
<td>eventName, {files, percentage}</td>
<td>triggered whilst uploading files</td>

<td>lu:success</td>
<td>eventName, {files, response}</td>
<td>triggered on a successful request to the server</td>

<td>lu:fail</td>
<td>eventName, {xhr}</td>
<td>triggered on a failed request to the server</td>

<td>lu:cancelled</td>
<td>eventName</td>
<td>triggered on upload abort</td>

Error Types

Below is an overview of the built-in error types that can be returned when validating files

• type - when file mime type does not match any mime types supplied in the rule.allowedFileTypes option
• size - when file size is above the size (in bytes) supplied in the rule.maxSize option
• refRequired - when there is no name attribute on the file input and no 'ref' options is passed to the plugin
• urlRequired - when no 'url' option is passed to the plugin

Public API

startUpload(files)

Starts the upload

<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>

<td>files</td>
<td>FileList (optional)</td>
<td>null</td>
<td>a list of files to be uploaded, takes priority over default mechanism if supplied</td>

addParam(key, value)

Allows parameters to be added after plugin instantiation

<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>

<td>key</td>
<td>String (required)</td>
<td>n/a</td>
<td>name of parameter to be added</td>

<td>value</td>
<td>String (required)</td>
<td>n/a</td>
<td>value of parameter to be added</td>

cancelUpload()

Allows the upload to be cancelled, triggers lu:cancelled

<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>

<td colspan="4">No parameters</td>

Browser Support

• Chrome 45+
• Firefox 34+
• Edge 12+
• Internet Explorer NO (because Promises and Object.assign are used)
• Safari 9+
• Opera 32+

License

Licensed under the MIT License.
View the full license here.