siraj / uppload

📁 Uppload is a better JavaScript image uploader

Uppload

Uppload is a better JavaScript file uploader. It's highly customizable, completely free and open-source, and can be used with any file uploading backend.

Table of Contents

• Usage
  • Browser Support
  • File Size
  • Configuration
  • Properties
  • Events
• Customization
• Server-side Implementation
  • Starter Templates
• Presets
  • Firebase
  • AWS S3
• Internationalization
• Wrappers
• Development
  • Roadmap
  • Installation
  • Local Setup
  • Production
• El Niño

Usage

Install Uppload in your project directory:

yarn add uppload

And then import it to your project:

import Uppload from "uppload";

You can also require it in your project since it ships as UMD, or use it from one of the CDNs below. You only need any one of the following, since wrappers come with Uppload built-in.

<!-- Uppload --><script src="https://unpkg.com/uppload/dist/uppload.min.js"></script> 
<!-- Uppload with polyfills --><script src="https://unpkg.com/uppload/dist/uppload.polyfills.js"></script> 

Create a new Uppload object with sample configuration:

const profilePicture = new Uppload({

    // Default file value, useful for empty-state images
    value: "https://randomuser.me/api/portraits/men/17.jpg",

    // Change the values of these elements with the file URL
    // Sets `value` for inputs and `src` for images
    bind: ["#profilePicInput", "#profilePicImage"],

    // Open the modal when the user clicks on this button
    call: ["form.profile button#uploadButton"],

    // Endpoint to send files to
    // Use either this or `uploadFunction` for a custom function
    endpoint: "https://example.com/upload_backend",

    // Maximum file size allowed in bytes (this is 25 MB)
    maxFileSize: 25000000,

    // Types of files to allow (string or MIME type array)
    allowedTypes: "image"

});

Browser Support

With babel-polyfill, Uppload works with IE11 and above. Without polyfills, it works with browsers that natively support both promises and the Fetch API. You can use the uppload.polyfills.js file to support older browsers, or manually import relevant polyfills (e.g. fetch(), etc.)

File Size

File	Size
Bundle

Configuration

You can pass the following properties in the constructor:

Property	Default	Type	Description
value	""	String	Default value of the file, useful for image placeholders
bind	["[data-uppload-value]"]	Array	Selectors for elements that need the uploaded file URL
call	["[data-uppload-button]"]	Array	Selectors for elements that open the modal on click
uploadFunction	Fetch (configurable)	Function	Function to upload file (returns promise with file URL)
endpoint	""	String	Endpoint to upload file using fetch POST
services	["upload", "camera"]	Array	List of upload services to show
defaultService	"upload"	String	List of default service
successDelay	1000	Number	Number of milliseconds to show the success screen for
minimumDelay	0	Number	Number of milliseconds to delay uploading by
errorDelay	2000	Number	Number of milliseconds to show an error message for
endpoint.url	""	String	Endpoint URL to fetch
endpoint.method	POST	String	HTTP verb, can be changed to PUT if necessary
endpoint.headers	null	Headers	HTTP headers to send with the request
allowedTypes	"*"	Array or String	MIME types to allow (eg. string "image/jpg" or array ["image/jpg", "image/png"]). Can also put MIME registry instead: "image", "audio", "font", "text", "video", etc.
maxFileSize	"infinite"	Number	Maximum allowed file size in bytes, defaults to string infinte
isFileTypeAllowed	Checks allowedTypes types	Function	Function to check whether file type is allowed (returns boolean)
isFileSizeAllowed	Checks maxFileSize	Function	Function to check whether file size is allowed (returns boolean)
i18n	English (US) dictionary	Object	Object for internationalization strings (configuration help)
crop.aspectRatio	null	Number	Aspect ratio for image cropping
crop.aspectButtons	[]	Array	Aspect ration buttons eg [{ text: "16:9", value: 16/9 }, ..]
crop.maxSize	null	[width, height, unit?]	Maximum image size after cropping
crop.minSize	null	[width, height, unit?]	Minimum image size after cropping
crop.startSize	[50, 50, "%"]	[width, height, unit?]	Default size when cropping starts
uploadFormat.type	image/jpeg	String	Image MIME type to upload to server
uploadFormat.quality	0.92	Number	Image quality to upload to server (between 0 and 1)

// Endpoint is an object with configuration
const withEndpointOptions = new Uppload({
    endpoint: {
        method: "POST",
        url: "/my_backend"
    }
});

// Custom file upload handler
const withCustomUpload = new Uppload({
    uploadFunction: (file, metadata) => {
        return new Promise((resolve, reject) => {
            fetch("https://example.com/upload", {
                method: "POST",
                body: file
            })
                .then(response => response.json())
                .then(json => {
                    let url = json.url;
                    resolve(url);
                })
                .catch(error => reject(error));
        });
    }
});

// Using an Uppload preset with configuration
const withUploadPreset = new Uppload({
    uploadPreset: {
        preset: "firebase",
        options: {
            storageRef: firebase.storage().ref()
        }
    }
});

Properties

You can use available properties to get information about the state of Uppload:

const profilePicture = new Uppload();
console.log(profilePicture.isOpen); // Returns true or false

Property	Default	Type	Description
isOpen	false	Boolean	Returns whether the modal is currently open
isUploading	false	Boolean	Returns whether a file is currently being uploaded
value	null	String	Returns the URL of the uploaded file
currentPage	"upload"	String	Returns the current page from navbar
modalElement	DOM Element	Object	Returns the modal HTML DOM element
backgroundElement	DOM Element	Object	Returns the background HTML DOM element

Events

For reactive frameworks, it doesn't make sense to use the native Uppload bind property. Instead, you can watch the Uppload.value and build around that URL value. Alternately, you can also listen to events using the on function:

const profilePicture = new Uppload();
profilePicture.on("fileUploaded", fileURL => {
	console.log(fileURL); // Logs the uploaded file's URL
});

Event	Dispatched when	Returns
fileSelected	A new file has been selected	Blob File
uploadStarted	Started to upload a new file	Blob File
uploadError	An error ocurred in uploading the file	Blob File
fileError	Invalid file (size/type/etc.) selected	Server's response
fileUploaded	A new file is uploaded	String File URL
fileDropped	A file has been dropped in the drop area	Blob File
modalOpened	The Uppload modal was opened	Nothing
modalClosed	The Uppload modal was closed	Nothing
pageChanged	User navigated to this uploading service	String Service ID
dragOver	A file is being dragged in the drop area	Nothing
dragEnter	File has entered the drop area	Nothing
dragLeave	File has left the drop area	Nothing
cropStart	Image has started being cropped	Object with crop details
cropMove	Image is currently being cropped	Object with crop details
cropEnd	Image has ended being cropped	Object with crop details

You can also programatically call the following functions:

const profilePicture = new Uppload();
profilePicture.openModal(); // Opens the modal

Function	Parameters	Description
uploadFile(param)	Blob File	Upload this file to the server (returns promise)
openModal()	None	Opens the modal
closeModal()	None	Closes the modal
updateValue(param)	String URL	Make this URL the post-uploading value
changePage(param)	String Service ID	Navigate to this uploading service

Customization

You can customize the widget using CSS to overwrite properties. The following classes are used by Uppload:

Selector	Description
.uppload-modal	Main white modal
.uppload-bg	Translucent background
.uppload-bg::after	Cross (×) button on the top-right
.uppload-modal aside	Left navbar
.uppload-modal section	Main content inside the modal
.uppload-branding	Small "Powered by Uppload" on the bottom-left
.uppload-(modal/bg).fadeIn	Fade in animation on open (400ms)
.uppload-(modal/bg).fadeOut	Fade out animation on close (400ms)
.uppload-modal .primary-button	"Upload" or "Import" call-to-action button
.uppload-modal #dragDropElement	Dashed "drag-and-drop here" area

Uppload also adds some classes to your elements that it interacts with:

Selector	Description
.uppload-initialized	Default value of file was set
.uppload-updated	New file was uploaded and set

Server-side Implementation

Uppload does not provide the server side implementation of handling the files, but the way files are uploaded is identical to simple file upload forms like this:

<form action="/upload_endpoint" method="post" enctype="multipart/form-data">
    <input type="file" name="file" />
</form>

Starter Templates

You can also use any of the following starter templates for your backend:

• Ruby on Rails
• PHP (Basic)
• Laravel
• Symfony 2 and AWS S3
• ASP.NET
• ServiceStack
• Golang

Presets

Instead of building your own backend or writing an upload handler, you can also use a preset:

const profilePicture = new Uppload({
    uploadPreset: {
        preset: PRESET_NAME,
        options: OPTIONS_OBJECT
    }
});

Preset Name	Configuration
firebase	storageRef contains the Firebase storage reference
s3	s3Object is the S3 object

Firebase

import firebase from "firebase";
firebase.initializeApp({
    apiKey: "YOUR_API_KEY",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_SUBDOMAIN.appspot.com",
});
const profilePicture = new Uppload({
    uploadPreset: {
        preset: "firebase",
        options: {
            storageRef: firebase.storage().ref()
        }
    }
});

AWS S3

This preset is current in development

import AWS from "aws-sdk";
AWS.config.update({
    region: "REGION",
    credentials: new AWS.CognitoIdentityCredentials({
        IdentityPoolId: "IDENTITY_POOL_ID"
    })
});
const s3 = new AWS.S3({
    apiVersion: "2006-03-01",
    params: { Bucket: "BUCKET_NAME" }
});
const profilePicture = new Uppload({
    uploadPreset: {
        preset: "s3",
        options: {
            s3Object: s3
        }
    }
});

Internationalization

Uppload comes with i18n support built-in. We have over 100 languages, but most of them are machine translated. You can overwrite all string by supplying a i18n property during initialization. The template is available here.

Wrappers

We've built the following wrappers for Uppload for our favorite frameworks:

• Vue.js (NPM uppload-vue)
• React (NPM uppload-react)
• Angular (NPM uppload-angular)

Development

Roadmap

• Modal
• File preview
• Image cropping
• Upload function
• Import file/image (Facebook, Dropbox, etc.)
• Add sample server configuration & files in docs
• IE support (customEvent)
• Basic and advanced docs
• Presets for Firebase, S3, etc.
• Wrappers for
  • Vue.js
  • React
  • Angular
• Use Tardis for module loading

Installation

yarn install
nvm use 8.11.1 # LTS

Local Setup

yarn start:dev

Navigate to http://localhost:9000

Production

yarn build

El Niño

Uppload is made with ❤️ in Enschede, the Netherlands by El Niño and contributors.

El Niño is een internetbureau uit Enschede. We hebben meer dan 12 jaar ervaring in het ontwikkelen van op maat gemaakte digitale oplossingen. Met een team van vakfanaten dragen we bij aan het succes van elke organisatie.

• Ben je student?
• Wil je samenwerken?