feature-exiffeature-giffeature-orientationfeature-transformfeature-uploadfeature-webhookslogo-marknav-arrowAsset 7Asset 8quote


Getting Started

Getting up and running with Shubox was designed to be quick and easy so you can get up back to working on your project. There are two parts to setting up Shubox — connecting your Amazon S3 account to Shubox, then integrating Shubox into your website. Let’s go!

Amazon S3 Setup

In order for Shubox to work it’s magic, it needs access to your Amazon S3 account with a few non-destructive permissions.

Step 1: Create an "Identity and Access Management" (IAM) User

Amazon's user management service "Identity and Access Management" (IAM), is how master AWS accounts manage users, groups, and the permissions to work with the different services. We would recommend that each site (and with further granularity - each domain) that works with Shubox to be an IAM user. Let’s make one:

Head over to the “Users” section of your AWS console and hit the “Add user” button:

user dashboard

We suggest creating a “shubox” user with programatic access:

add user

Attach the `AmazonS3FullAccess` policy, then review and create the user:

set permissions

Not comfortable with granting Shubox full permissions? That’s okay, we only need following permissions to do our work: s3:ListBucket s3:CreateBucket s3:PutBucketCORS s3:PutObject

Review and create the user:

review and create user

Grab your access key id and secret access key:

great success

Connect Your Domain to Shubox

Step 2: Now that your Amazon IAM user is set up, you can head over to your Shubox dashboard and add a new domain. A unique bit of JavaScript will be created for your domain. You’re going to need that next.

Website Integration

It’s time to fire up your code editor! We’re going to connect your website to Shubox. Place the javascript snippet that shubox provided just before <body> in your HTML template:

    <script src="/x/abc12300.js"></script>


Now all we have to do is bind Shubox to a form element:

<script type="text/javascript" charset="utf-8">
  // with no options
  new Shubox("#dragndrop");

  // with custom options - note: `optionKey` is just an example
  new Shubox("#dragndrop", { optionKey: 'option value' });


From here you can use our [JavaScript API](#JavaScriptAPI) to create the file uploader of your dreams. If you’d rather get started fast, check out our [example/demo uploaders](/demos) here or on codepen. Feel free to incorporate those into your project, customize them, or use them to learn the ropes.

Local Development

Shubox only needs the domain for your website. The only requirements are that the domain is running on a web server (i.e. https://mydomain.com, http://mydomain.dev, or http://localhost:[port]). They may be a combination of an http(s) protocol, hostname, domain name, and port.

Domains must be unique in our system, which makes local development domains, like http://localhost:3000, problematic -- once a localhost domain and port are taken in our system, they are no longer available.We suggest proxying your local development domain with Pow.cx, Puma Dev, Laravel Valet or something similar.

JavaScript API



Assign a function to the success key that accepts a file parameter which will be run after files are successfully uploaded. More information about the File type passed into this function can be found below.

success: function(file) {}


Assign a function to the error key which accepts a file object and an error string and it will be run when errors are incurred with a file upload.

error: function(file, message) {}


The queuecomplete callback will be called when all files are finished uploading.

queuecomplete: function() {}



When uploading to a form element, the element's value will be changed to the URL of the uploaded file, which is, according to the default value of this option, a handlebars-like representation of the S3 URL - ''.

This can be changed to any string, and if it has the '' string anywhere within it, it will be interpolated with the final uploaded file's address. Example, to instead insert markdown's image pseudo code you would change this to '![alt text]()'.

s3urlTemplate: ''


When uploading through a form element (<input>, <textarea>, etc) the behavior, by default, will be to 'replace' the contents of the form element value with the URL to the newly uploaded file.

Changing the value to 'append' will append the resulting value from the newly uploaded file to the form element.

textBehavior: 'replace' // default value


Any element initialized with Shubox will, by default, trigger the file dialog when clicked.

Setting this to false will turn it off, but will still allow dragging and dropping into the element.

Changing the value to a valid CSS selector pointing to another element will allow that other element to trigger the file dialog instead of the main target element Shubox is initialized with. For a more comprehensive example see this blog post for a common use case where this is utilized.

clickable: true // default value


Because much of the JS under the hood is handled by the excellent dropzone.js javascript library Shubox makes use of its conventions where it makes sense. The previewTemplate option takes a string containing an html template which Dropzone will use to render a preview image for each dropped image. For more information on how to theme the elements generated by the default string you may visit the DropzoneJS website and get an idea for what you can do by "theming" the resulting UI.

 var myTemplate = '<div class=\"dz-preview dz-file-preview\">' +
'  <div class=\"dz-details\">' +
'    <div class=\"dz-filename\"><span data-dz-name></span></div>' +
'    <div class=\"dz-size\" data-dz-size></div>' +
'    <img data-dz-thumbnail />' +
'  </div>' +
'  <div class=\"dz-progress\"><span class=\"dz-upload\" data-dz-uploadprogress></span></div>' +
'  <div class=\"dz-success-mark\"><span>😄</span></div>' +
'  <div class=\"dz-error-mark\"><span>😩</span></div>' +
'  <div class=\"dz-error-message\"><span data-dz-errormessage></span></div>' +

previewTemplate: myTemplate


Shubox provides a mechanism with which to post custom data via an AJAX webhook to any address of your own choosing whenever files are uploaded. This will allow you to share any information available during your users' session. The information within the `extraParams` hash will be sent to your webhook endpoint along with the data from the uploaded file.

As an example, you may want to send data about the uploaded file(s) with a user's ID or email. It's not uncommon to want to know who is uploading a particular file.

extraParams: { // defaults to empty object
  userID: 123,
  userEmail: [email protected]'

File Object

Upon successful upload of an image the Shubox library will pass a file object to all JavaScript callbacks. The format of this file object follows:

  accepted: true,
  custom_status: "ready",
  name: "my-upload.jpg",                          // filename w/ext
  width: 281,                                     // in pixels
  height: 500,                                    // in pixels
  size: 15596,                                    // in bytes
  lastModified: 1446064073000,
  lastModifiedDate: Sun Jan 1 2016 00:00:01 ...,  // Date Object
  postData: {
    AWSAccessKeyId: "...",                        // AWS Key
    Content-Type: "",
    acl: "public-read",
    key: "path/to/file/in/bucket/filename.jpg",
    policy: "...",                                // policy string
    signature: "...",                             // signature string
    success_action_status: "201"                  // HTTP response code
  processing: true,
  s3: "path/to/file/in/bucket/filename.jpg",
  s3Url: "https://bucket.s3.amazonaws.com/path/to/file...",
  status: "success",
  type: "image/jpeg",
  upload: {
    bytesSent: 999,
    total: 999,
    progress: 100