Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Legacy Shubox JavaScript Api

The "legacy" Shubox JavaScript library is the first version of the library where the bulk of the initial features were built. The legacy code is similar to, but not the same as, the new Shubox library. The biggest differences between the legacy and the new version are:

  1. The legacy library had each JS file generated specifically for each domain that is created on the Shubox dashboard. There is hard-coded configuration in each JS file that is then uploaded to our CDN where the file(s) can be referenced directly. The new js lib is one package released to NPM for anyone to download, use, and configure as needed.
  2. The legacy library was written in plain, vanilla JS, whereas the new library is written with Typescript, and output to a UMD module that can be used via standalone script src, commonjs, or es2015 modules.
  3. The new library is open source. The old library is not.
  4. The new library has a lot of new and cool features.

Going forward you should use the new library, but the old one will remain around for a while until we stop generating new versions of the file.

Below is the documentation for the previous version of the library that had lived at



The sending callback is called just before each file is sent. It receives file[1], xhr, and formData objects. This allows you to modify any or all of these object before they go in flight to your endpoint (to add headers, etc).

sending: function(file, xhr, formData) {}


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

s3urlTemplate: '{{s3Url}}'


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

new Shubox('#my-selector', {
  previewTemplate: myTemplate


Defines where to display the file previews. If null the target Shubox element itself is used. Can be a plain HTMLElement or a CSS selector. A demo that uses this can be found on CodePen here.

previewsContainer: null // the default
previewsContainer: '#selector'
previewsContainer: document.querySelector('#dom-element')


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


If you only want certain file types allowed to be uploaded, you may provide a list of mime types or extensions. The contents of the option may include a comma separated list of mime types or file extensions. Eg.:

acceptedFiles: "image/*,application/pdf,.psd"