Box Developer Platform

Box Content Preview

The Box Content Preview Javascript UI Kit allows developers to easily embed high quality and interactive previews of Box files in their desktop or mobile web application. The library fetches information about the file and its converted representations through the Box API, chooses the appropriate viewer for the file type, dynamically loads the necessary static assets and file representations, and finally renders the file. Box Content Preview also allows previews of multiple files to be loaded in the same container and exposes arrows to navigate between those files.

This UI Kit powers Preview in the main Box web application as well as the 'expiring embed' Box API endpoint.

Browser Support

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

If your browser doesn't natively support Promises, include a Promise library (e.g. Bluebird) before the main Preview script.

Current Version

  • Version: 0.111.0
  • Locale: en-US

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

Update to v0.101.0 or higher

If you are using a version of the SDK prior to v0.101.0, please upgrade to v0.101.0 or higher. We have made necessary breaking changes to the underlying API that serves converted representations in order to support more use cases and improve clarity.

Supported Locales

To use a different locale, replace en-US in the URLs above with any of the following supported locales.

en-AU, en-CA, en-GB, en-US, 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

Supported File Types

Box Content Preview supports 100+ file types, including most document and image formats, HD video, 3D models, 360-degress images, and 360-degree videos. You can find the full list of supported file types at https://community.box.com/t5/Managing-Your-Content/What-file-types-and-fonts-are-supported-by-Box-s-Content-Preview/ta-p/327#FileTypesSupported.

Usage

You can self-host the Box Content Preview UI Kit and Promise library or reference the versions hosted on the Box CDN.

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

    <!-- Include Promise library if using Internet Explorer 11 -->
    <script src="https://cdn01.boxcdn.net/js/vendor/bluebird/bluebird-core-some-any-cancel-settle-2.9.34.js"></script>

    <!-- Latest version of Box Content Preview for en-US locale -->
    <script src="https://cdn01.boxcdn.net/platform/preview/0.111.0/en-US/preview.js"></script>
    <link rel="stylesheet" href="https://cdn01.boxcdn.net/platform/preview/0.111.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>

CORS (Cross-Origin Resource Sharing)

For security purposes, you must whitelist your application's HTTP origin, omitting any trailing slash, in the configuration section of the Developer Console. For example, CodePen's domain is whitelisted for the demo application below.

Box Content 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

Box Content Preview 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.

Events

The preview object exposes addListener and removeListener for binding to events. Event listeners should be bound before show() is called, otherwise events can be missed.

Viewer Events

The full list of events that each individual viewer fires can be found at https://docs.box.com/docs/file-types-events.

const listener = (value) => {
    // Do something with value
};

// Attach listener before calling show otherwise events can be missed
Box.Preview.addListener(EVENTNAME, listener);

// Show a preview
Box.Preview.show(...);

// Remove listener when needed
Box.Preview.removeListener(EVENTNAME, listener);

EVENTNAME can be one of the following

  • viewer event will be fired when we have the viewer instance first available. This will be the same object that is also a property included in the load event. Preview fires this event before load so that clients can attach their listeners before the load event is fired.

  • load event will be fired on every preview load when show() is called or if inter-preview navigation occurs. The event data will contain:

error: 'message', // Error message if any error occurred while loading
viewer: {...},    // Instance of the current viewer object if no error occurred
metrics: {...},   // Performance metrics
file: {...}       // Box file object with properties defined in file.js
  • navigate event will be fired when navigation happens. The event includes the file ID of the file being navigated to, and this event will fire before load.

  • notification event will be fired when either the preview wrapper or one of the viewers wants to notify something like a warning or non-fatal error. The event data will contain:

message: 'message', // Message to show
type: 'warning'    // 'warning', 'notice', or 'error'
  • viewerevent Each viewer will fire its own sets of events. For example, the Image viewer will fire rotate or resize, etc. while other viewers may fire another set of events. The full list of events can be found at https://docs.box.com/docs/file-types-events. The preview wrapper will also re-emit events at the preview level, with event data containing:
event: EVENTNAME,         // Event name
data: DATA,               // Event data object
viewerName: VIEWERNAME,   // Name of the viewer. See VIEWERNAME above
fileId: fileId            // The file ID

Example event usage

Box.Preview.addListener('viewer', (viewer) => {
    viewer.addListener('rotate', () => {
        // Do something when a viewer rotates a preview
    });
});

Box.Preview.addListener('load', (data) => {
    const viewer = data.viewer;
    viewer.addListener('rotate', () => {
        // Do something when a viewer rotates a preview
    });
});

Box.Preview.addListener('viewerevent', (data) => {
    if (data.viewerName === 'Image') {
        if (data.event === 'rotate') {
            // Do something when an image preview is rotated
        }
    } else if (data.viewerName === 'Image360') {
        if (data.event === 'rotate') {
            // Do something different when a 360-degree image is rotated
        }
    } else {}
});

Box.Preview.addListener('rotate', (data) => {
    if (data.viewerName === 'Image') {
        // Do something when an image preview is rotated
    } else if (data.viewerName === 'Image360') {
        // Do something different when a 360-degree image is rotated
    } else {}
});

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


Box Content Preview