Box Javascript Preview SDK

The Box Javascript Preview SDK allows developers to easily embed previews of Box files in a web application. The SDK fetches information about the file and its converted representations through the Box Content API, chooses the appropriate viewer for the file type, dynamically loads the static assets and file representations needed, and finally renders the preview client-side. The SDK also allows previews of multiple files to be loaded in the same container and exposes arrows to navigate between those files.

Browser Support

  • Desktop Chrome, Firefox, Safari, Edge, and Internet Explorer 11
  • Limited support for mobile web - files will render but some controls may not work, full support will come soon.

The browser needs to have the Promise API implemented. If not, it can be polyfilled by including a promise library (e.g. Bluebird - https://cdn.jsdelivr.net/bluebird/latest/bluebird.min.js) before including any other script.

Current Version

  • Version: 0.96.0
  • Locale: en-US

https://cdn01.boxcdn.net/platform/preview/0.96.0/en-US/preview.js
https://cdn01.boxcdn.net/platform/preview/0.96.0/en-US/preview.css

Usage

<!DOCTYPE html>
<html lang="en-US">
<head>
    <meta charset="utf-8" />
    <title>Preview SDK Demo</title>

    <!-- Polyfill promise API if using Internet Explorer -->
    <script src="https://cdn.jsdelivr.net/bluebird/latest/bluebird.min.js"></script>

    <!-- Latest version of Preview SDK for en-US locale -->
    <script src="https://cdn01.boxcdn.net/platform/preview/0.96.0/en-US/preview.js"></script>
    <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/preview/0.96.0/en-US/preview.css" />
</head>
<body>
    <div class="preview-container" style="height:400px; width:100%;"></div>
    <script>
        Box.Preview.show('93392244621', 'EqFyi1Yq1tD9mxY8F38sxDfp73pFd7FP', {
            container: '.preview-container',
            showDownload: true
        });
    </script>
</body>
</html>

Preview Demo

Use the navigation arrows to preview different file types.

Initialization and Options

To show a preview, call Box.Preview.show(fileId, accessToken, { options }). Parameters and options are described below.

Box.Preview.show(fileId, accessToken, {
    container: '.preview-container',
    sharedLink: 'https://app.box.com/v/foo',
    sharedLinkPassword: 'bar',
    collection: [fileId, '123', '234', ...],
    header: 'light',
    logoUrl: 'http://i.imgur.com/xh8j3E2.png',
    showDownload: true,
});
Parameter
Description

fileId
string

Box File ID.

accessToken
string

Box API access token to use.

Option
Default
Description

container
string

document.body

CSS selector of the container in which Preview should be placed.

sharedLink
string

Shared link URL, required if file 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.

collection
array

List of file IDs to preview over. When used, this will show previews of multiple files within the same container and expose arrows to navigate between those files. Note that FILE_ID needs to be included in this list and that the SDK doesn't support collections with files that require a shared link or password.

header
string

'light'

Values that control header visibility and background color. Use 'none' for no header, 'light' for a light header and background, and 'dark' for a dark header and background.

logoUrl
string

Box logo

URL of custom logo to show in header.

showAnnotations
boolean

false

Whether annotation button in header and annotations on content are shown.

showDownload
boolean

false

Whether download button is shown in header. Will also control print button visibility in viewers that support print. Note that this option will not override download permissions on the access token.

Access Token

The Preview SDK needs an access token to make Box Content 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/).

Additional Methods

These additional methods are available once a preview is loaded.

Box.Preview.hide() hides the preview.

Box.Preview.print() prints the file if printable.

Box.Preview.download() downloads the file if downloadable.

Box.Preview.resize() resizes the current preview if applicable. This function only needs to be called when preview's viewport has changed while the window object has not. If the window is resizing, then preview will automatically resize itself.

Box Javascript Preview SDK