Content Uploader

The Box Content Uploader UI Element allows developers to embed an upload widget in their desktop or mobile web application. Users can select files or use drag and drop to upload. Large files will be uploaded with the Chunked Upload API.

Browser Support

  • Chrome, Firefox, Safari, and Edge (latest 2 versions)
  • Limited support for IE11 (requires ES2015/Intl polyfill)
  • Mobile Chrome and Safari

Box UI Elements require an ES2015-capable browser supporting Intl (ECMAScript Internationalization API). If your application supports Internet Explorer 11 or Safari 9, please include your favorite polyfill library or a service like polyfill.io to smartly load only the polyfills your users need. Box also hosts the core-js standard library at https://cdn01.boxcdn.net/polyfills/core-js/2.5.3/core.min.js.

Assets

Current Version

  • 7.2.0

Prior Version

  • 7.1.1

NPM

Scripts and Stylesheets

Supported Locales

The above asset URLs use en-US. If you want to use another locale, then replace en-US in the URLs above with any of the following:

en-AU, en-CA, en-GB, da-DK, de-DE, es-ES, fi-FI, fr-CA, fr-FR, it-IT, ja-JP, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, ru-RU, sv-SE, tr-TR, zh-CN, zh-TW

Source Code

Source code for the Uploader Element and others are hosted on GitHub. The repository contains detailed documentation for usage and development. Please file any bugs you encounter under the 'Issues' tab with clear steps to reproduce.

https://github.com/box/box-ui-elements

Releases

https://github.com/box/box-ui-elements/releases

Usage

There are two ways to use the Box Content Uploader. If you’re looking to build something quick and simple, use it as a library as shown below in this documentation. Alternatively, if you are a building a React based app, you can pull in the component from our NPM package. For details refer to the NPM link above. As we continue to roll this out, we will provide some level of access to the source.

Cross Origin Resource Sharing

For the API calls to work from your own domain, you will need to whitelist your HTTP origin for CORS. This setting can be found in the Developer Console, under the configuration section of your app. For example, in the following image codepen.io is whitelisted since we use it for our demos below.

Sample HTML

<!DOCTYPE html>
<html lang="en-US">
<head>
    <meta charset="utf-8" />
    <title>Box Content Uploader Demo</title>

    <!-- polyfill.io only loads the polyfills your browser needs -->
    <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=es6,Intl"></script>
    <!-- Alternatively, use polyfill hosted on the Box CDN
    <script src="https://cdn01.boxcdn.net/polyfills/core-js/2.5.3/core.min.js"></script> 
    -->

    <!-- Latest version of the uploader css for your locale -->
    <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/elements/7.2.0/en-US/uploader.css" />
</head>
<body>
    <div class="container" style="height:600px"></div>
    <!-- Latest version of the uploader js for your locale -->
    <script src="https://cdn01.boxcdn.net/platform/elements/7.2.0/en-US/uploader.js"></script>
    <script>
      	var folderId = '123';
      	var accessToken = 'abc';
      	var uploader = new Box.ContentUploader();
      	uploader.show(folderId, accessToken, {
            container: '.container'
        });
    </script>
</body>
</html>

Demos

Access Token

The demos below may not fully function until you provide a valid access token. For testing purposes, you can use your temporary developer token which can be generated in the Box Developer Console. This will need to be updated under the JS/Babel tab in the demo.

Content Uploader

Content Uploader as a popup

Authentication

UI Elements are compatible with both OAuth and JWT

The UI Elements are designed in an authentication-type agnostic way so whether you are using UI Elements for users who have Box accounts (Managed Users) or non-Box accounts (App Users), UI Elements should just work out of the box. The reason for this is that UI Elements only expect a "token" to be passed in for authentication, and Box provides two different ways to generate tokens - OAuth and JWT.

So depending on which type of app you are building, follow the linked authentication guides above on how to generate access tokens, and refer to the UI Elements documentation below how to pass along those tokens to the Content Uploader UI Element.

If you have any questions, please visit our developer forum.

The Uploader UI Element needs an access token to make Box API calls. You can either get an access token from the token endpoint (https://docs.box.com/reference#token) or generate a developer token on your application management page (https://blog.box.com/blog/introducing-developer-tokens/).

Tokens on the client

We strongly suggest that before you put this UI Element into production, you leverage the appropriate scope to avoid putting a fully scoped token into the client. See the Scopes section for how to choose and use scopes.

API

const { ContentUploader } = Box;
const uploader = new ContentUploader();

/**
 * Shows the content uploader.
 *
 * @public
 * @param {String} folderId - Folder ID to upload to.
 * @param {String} accessToken - Box API access token.
 * @param {Object|void} [options] - Optional options.
 * @return {void}
 */
uploader.show(folderId, accessToken, options);

/**
 * Hides and clears HTML for the uploader.
 *
 * @public
 * @return {void}
 */
uploader.hide();

/**
 * Adds an event listener to the content uploader.
 * Listeners should be added before calling show()
 * so no events are missed.
 *
 * @public
 * @param {String} eventName Name of the event.
 * @param {Function} listener Callback function.
 * @return {void}
 */
uploader.addListener(eventName, listener);

/**
 * Removes an event listener from the content uploader.
 * 
 * @public
 * @param {String} eventName Name of the event.
 * @param {Function} listener Callback function.
 * @return {void}
 */
uploader.removeListener(eventName, listener);

/**
 * Removes all event listeners from the content uploader.
 * 
 * @public
 * @return {void}
 */
uploader.removeAllListeners();

Parameters

Parameter
Type
Description

folderId

String

Box Folder ID. This will be the ID of the folder from which you want files to be uploaded to. If you want to use the Box All Files folder, then use '0' as the folderId.

accessToken

String

Box API access token to use. This should have upload access to the folder above. The value passed in for the token is assumed to never expire while the uploader is visible.

options

Object

Optional options. See below for details.

Options

Option
Type
Default
Description

container

String

document.body

CSS selector of the container in which the content uploader should be placed. Calling hide() will clear out this container.

sharedLink

String

Shared link URL, required if folder is shared and the access token doesn't belong to an owner or collaborator of the file. See https://docs.box.com/reference#get-a-shared-item for more details.

sharedLinkPassword

String

Shared link password, required if shared link has a password. See https://docs.box.com/reference#get-a-shared-item for more details.

onClose

Function

Callback function for 'Close' button, which will appear when there are no files to upload or when all uploads are complete. If this option is not defined, the button will not appear.

modal

Object

When the modal attribute is specified, then the content uploader will not be created in-place. Instead a button will be created in the container and clicking this button will launch the content uploader in a modal popup.

See below for the modal options.

size

String

undefined

Indicates to the content uploader to fit within a small or large width container.

Value can be absent or one of small or large. If absent the UI Element will adapt to its container and automatically switch between small width or large width mode.

isTouch

Boolean

The result of 'ontouchstart' in window || (window.DocumentTouch && document instanceof window.DocumentTouch)

Indicates to the content uploader that it's is being rendered on a touch enabled device.

fileLimit

Number

100

The maximum number of files that can be uploaded at once. If more than fileLimit files are selected for upload, any beyond the first fileLimit files will not be included for uploaded. A warning message will be shown in the footer when this happens.

requestInterceptor

Function

Function to intercept requests. For an example see https://codepen.io/box-platform/pen/jLdxEv

Our underlying XHR library is axios.js and we follow a similar approach for interceptors: https://github.com/axios/axios#interceptors

responseInterceptor

Function

Function to intercept responses. For an example see https://codepen.io/box-platform/pen/jLdxEv

Our underlying XHR library is axios.js and we follow a similar approach for interceptors: https://github.com/axios/axios#interceptors

Options for the modal attribute

Option
Type
Default
Description

buttonLabel

String

Label for the button.

buttonClassName

String

Box Blue Button

CSS class to decorate the button.

modalClassName

String

CSS class to decorate the modal popup content.

overlayClassName

String

CSS class to decorate the modal popup overlay.

Events

Event Name
Event Data
Description

close

Will be fired when 'Close' button is clicked.

complete

Array<File>

Will be fired when all uploads in the current view are complete. Event data will be an array of File Object.

upload

Fired when a single file is successfully uploaded. Event data will be a File Object.

error

Object

Fired when a single file has an upload error. Event data will be an object with properties file from the File Web API and the error object error.

Scopes

We strongly suggest that before you put this UI Element into production, you leverage the appropriate scope to avoid putting a fully scoped token into the client.

If your application requires the end user to only be able to access a subset of the Content Uploader functionality, you can use Token Exchange to appropriately downscope your App/Managed or Service Account token to a resulting token that has the desired set of permissions, and can thus, be securely passed to the end user client initializing the Content Uploader.

Below are a set of new UI Element-specific scopes to go alongside Token Exchange. These allow developers to enable/disable UI controls on the Content Uploader by configuring the appropriate scopes on the downscoped token. To learn more, see Special Scopes for Box UI Elements.

Wish to learn more about when, why and how you can use Token Exchange with the Content Uploader? See our blueprint on Customizing Access for the Box UI Elements.

Base Scope

Scope Name
What permissions does it grant?

base_upload

Allows upload into the folder specific under "resource" of the Token Exchange request.

Feature Scopes

None

Sample Scenarios

Scope Name
Scope Combinations in Token Exchange Request

User wants to upload files to a Box folder

base_upload

Questions

If you have any questions, please visit our developer forum or contact us via one of our available support channels.

Please file any bugs you encounter with clear steps to reproduce at https://github.com/box/box-ui-elements/issues.