Documentation & Guides

Initial Setup

After creating your domain's config you will be given a snippet of javascript to add to your website. Place it near the end of your html (layout, template, theme) before the closing </body> tag, or somewhere in your <head /> tag.

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

Point Shubox towards one of your page's elements, whether that is a div, an input or a form element. We will cover the ways to customize the behavior below.


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

  // with custom options
  new Shubox("#dragndrop", { optionKey: 'option value' });

The options you may provide for configuration follow...


After adding a domain to your account you may set up shubox to apply some Transformations to the images that are uploaded. The following steps will get you to a point where images are uploaded, transformed, and placed right alongside your original image.

  1. Create a new transform
    • Name the transform
    • Select the domains / buckets that you would like to allow the transform to be applicable.
    • Select the transformations you would like to be applied to newly uplaoded images -- stripping exif data, resizing the images, auto-orientation, etc.
  2. In your website, create your uploader element as you normally would.
  3. To signify that images being uploaded through this uploader element need to have your new image transformation applied to it, apply the data attribute data-shubox-transform to the element, with the value being the name of your new image transformation.


If I have just set up an image transformation called "blog-post-images", and I have an uploader html element resembles the following:

<div id="blog-photos"></div>

To get all images uploaded through that to be run through the transform process I would change it to:

<div id="blog-photos" data-shubox-transform="blog-post-images"></div>

Where do newly generated images end up?

Newly generated image files are prefixed with a descriptor saying what transformation was applied and are uploaded to the same path in the S3 bucket.

How do I know when those files are successfully generated and uploaded?

We recommend using the image transform webhook event to notify your app when new transformations are complete. The webhook will send you a collection of meta data about all of the generated images, which you can use to update references to your image(s).


Key Default Value Description
success function(file){} Assigning a function to the success key that accepts a file parameter will be run after files are successfully uploaded. More information about the File type passed into this function can be found below.
error function(file, message){}

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.

queuecomplete function(){}

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

addedfile function(file){}

The addedfile callback will be called when a file has been added to the list of files to be uploaded.

s3urlTemplate '{{s3Url}}'

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 - '{{s3Url}}'.

This can be changed to any string, and if it has the '{{s3Url}}' 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]({{s3Url}})'.

textBehavior 'replace'

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.

clickable true

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.

previewsContainer null

The element object or css selector that will display the file previews. By default it is set to null and will display inside the element that will receive the shubox upload events.

maxFiles null

Limit the number of files that can be uploaded through your element. By default it is set to null and has no limit. If set it will enforce with a warning that the max number of files has been exceeded.

acceptedFiles 'image/*'

Limit the kinds of files that may be uploaded via the Shubox object. By default this will look for images only, but if you would like to accept something else, provide a comma delimited list of mime types or file extensions. Eg: 'image/*,application/xls,.gif'

'<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>' +

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.

extraParams {}

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 through your website. This allows you to share any information available during your users' session. For example, you may send data about the uploaded files alongside a user's ID or email. It's not uncommon to want to know WHO is uploading a particular file, no?

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, for your reference:

  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: ""
  status: "success",
  type: "image/jpeg",
  upload: {
    bytesSent: 999,
    total: 999,
    progress: 100


The simplest example

<div id="dragndrop">Drag and Drop in Here</div>

  new Shubox("#dragndrop");

The code snippit above will allow that div to be drag 'n drop'able, or clicked directly to display the files dialog.

Uploading into <input> tags

<input name="my_file" id="my_file" value="">

  new Shubox("#my_file", { textBehavior: "append" });

This code will attach to a form input tag, allowing to drag and drop, and to click into it to select files. When files are successfully uploaded the URL to the file will be appended to the contents of the element, separated by a space.

Default textBehavior is to replace the contents with the new url(s).

For example:

  // The default textBehavior is "replace" so
  // these examples are equivalent
  new Shubox("#my_file");
  new Shubox("#my_file", { textBehavior: "replace" });

Uploading into <textarea> tags

<textarea name="my_comment" id="my_comment"></textarea>

  new Shubox("#my_comment", {
    textBehavior: "append",
    clickable: false

This code will attach to a textarea, allowing to drag and drop, but will not allow the elements' being clicked to trigger a file dialog to be displayed.

Default clickable value is true.

Uploading into <textarea> with adjacent clickable element

Sort of like GitHub's comment fields.

<textarea name="my_comment" id="my_comment"></textarea>

<p id="drag-and-drop">
  Attach files by dragging &amp; dropping.

  new Shubox("#my_comment", {
    textBehavior: "append",
    clickable: "#drag-and-drop"

This code will attach to a textarea, allowing to drag and drop, but will not trigger a file select dialog to pop up when the textarea is clicked/focused on.

Default clickable value is true.

Uploading into <textarea> and appending custom s3 URL text

<textarea name="my_comment" id="my_comment"></textarea>

<p id="drag-and-drop">
  Attach files by dragging &amp; dropping.

  new Shubox("#my_comment", {
    textBehavior: "append",
    clickable: "#drag-and-drop",
    s3urlTemplate: '<img src="{{s3url}}">'

The s3urlTemplate option provides the ability to have a custom string, with the S3 URL, added to the textarea, or text input, upon successful upload. This allows you to append an image tag, with the src set to the uploaded file URL, or a markdown image tag, etc.

The default is "{{s3url}}".

Adding extra information for post-upload webhook

If you need to save extra information for your uploads -- example: you need to associate a user's id with an uploaded image -- you may add any arbitrary hash to the payload sent to your post-upload webhook. The hash you assign to the extraParams option upon Shubox instantiation will be sent after each file is uploaded.

<div id="dragndrop">Drag and Drop in Here</div>
  new Shubox("#dragndrop", {
    extraParams: {
      user_id: 1,
      user_name: "Lawrence Cohen",
      nickname: "Chunk"

Using a post-upload callback on a successful upload

If you want something to happen after a successful upload, provide a function through the success option.

<div id="dragndrop">Drag and Drop in Here</div>
  new Shubox("#dragndrop", {
    success: function(file){

Using a post-upload callback on a failed upload

What if something fails*? Ugh. Bummer. You can hook into a callback here too.

<div id="dragndrop">Drag and Drop in Here</div>
  new Shubox("#dragndrop", {
    error: function(file, message){

* Possible errors: file is too big, or too many files are uploaded at once.