Box UI Elements

Box UI Elements are pre-built UI components that allow developers to add features of the main Box web application into their own applications. They can be used to navigate through, upload, preview, and select content stored on Box and are available both as React components and framework-agnostic JavaScript libraries.

Usage

The instructions below describe how to use the UI Elements in a React application. If instead you would like to include the framework-agnostic libraries as scripts, refer to our developer documentation. Continue reading below for how to import the UI Elements as React components. You can also reference https://github.com/box/box-ui-elements-demo or https://github.com/box/box-content-preview-demo for minimal React applications using the Explorer UI Element and Preview UI Element respectively.

Installation

yarn add box-ui-elements or npm install box-ui-elements

Browser Support

• Desktop Chrome, Firefox, Safari, Edge (latest 2 versions)
• Limited support for Internet Explorer 11 (requires ES2015 polyfill)
• Mobile Chrome and Safari

Available 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

The NPM package includes translated messages for the above locales. See the examples below on how to reference them. You can also use your own translated messages since the components are essentially locale free and only require a getLocalizedMessage function to be passed in. The getLocalizedMessage function in the examples below accepts a string message id and returns a formatted string after some optional string replacements. Alternatively, if your React app is using the popular react-intl library, you can instead use formatmessage to do the replacements.

Authentication

We have designed the Box UI Elements in an authentication-type agnostic way. Whether you are using them for users who have Box accounts (Managed Users) or non-Box accounts (App Users), they should just work out of the box. They only expect an access token to be passed in for authentication. The developer documentation contains more information on how to generate and use these access tokens.

CSS

The Box UI Elements require their corresponding CSS stylesheets to render properly. You will need to set up Webpack's style-loader and css-loader in order to properly include the CSS like in the examples below. Alternatively, you can include the appropriate CSS files in your application's HTML without importing it in React. Links to hosted versions of these CSS files on the Box CDN can be found in the documentation links below.

Components

You can import the ContentExplorer, ContentPicker, ContentUploader, ContentPreview or ContentTree. Similarly, you can also import the ContentPickerPopup, ContentUploaderPopup or ContentTreePopup which are popup versions for the Content Picker, Content Uploader and Content Tree, respectively.

Content Explorer (Documentation)

import React from 'react';
import { render } from 'react-dom';
import { ContentExplorer } from 'box-ui-elements';
import messages from 'box-ui-elements/lib/i18n/en-US';
import 'box-ui-elements/dist/explorer.css';

const token = 'ACCESS_TOKEN';
const getLocalizedMessage = (id, replacements) =>
    messages[id].replace(/{\s*(\w+)\s*}/g, (match, key) => replacements[key]);

render(
    <ContentExplorer
        token={token}
        getLocalizedMessage={getLocalizedMessage}
    />,
    document.querySelector('.container')
);

Props

Prop	Type	Default	Description
token*	string		See the developer docs.
getLocalizedMessage*	function(string, { [string]: string })		Function to get localized strings.
rootFolderId	string	0	The root folder for the content explorer.
currentFolderId	string		The current folder shown for the content explorer. This should be a sub folder to the root folder.
sortBy	string	name	See the developer docs.
sortDirection	string	asc	See the developer docs.
canPreview	boolean	true	See the developer docs.
canDownload	boolean	true	See the developer docs.
canDelete	boolean	true	See the developer docs.
canUpload	boolean	true	See the developer docs.
canRename	boolean	true	See the developer docs.
canShare	boolean	true	See the developer docs.
canSetShareAccess	boolean	true	See the developer docs.
onDelete	function(Array<File>)		Callback function for when item(s) are deleted.
onDownload	function(Array<File>)		Callback function for when item(s) are downloaded.
onPreview	function(File)		Callback function for when an item is previewed.
onRename	function(File)		Callback function for when an item is renamed.
onSelect	function(Array<Folder|File|Web Link>)		Callback function for when item(s) are selected.
onUpload	function(Array<File>)		Callback function for when item(s) are uploaded.
onCreate	Folder>)		Callback function for when a folder is created.
onNavigate	function(File)		Callback function for when navigating into a folder.
isTouch	boolean		See the developer docs.
autoFocus	boolean		See the developer docs.
logoUrl	string		See the developer docs.
sharedLink	string		See the developer docs.
sharedLinkPassword	string		See the developer docs.
defaultView	string	files	See the developer docs.
responseFilter	function		See the developer docs.

Keyboard Shortcuts

See the developer docs.

Content Picker (Documentation)

import React from 'react';
import { render } from 'react-dom';
import { ContentPicker } from 'box-ui-elements';
import messages from 'box-ui-elements/lib/i18n/en-US';
import 'box-ui-elements/dist/picker.css';

const token = 'ACCESS_TOKEN';
const getLocalizedMessage = (id, replacements) =>
    messages[id].replace(/{\s*(\w+)\s*}/g, (match, key) => replacements[key]);

render(
    <ContentPicker
        token={token}
        getLocalizedMessage={getLocalizedMessage}
    />,
    document.querySelector('.container')
);

Props

Prop	Type	Default	Description
token*	string		See the developer docs.
getLocalizedMessage*	function(string, { [string]: string })		Function to get localized strings.
rootFolderId	string	0	The root folder for the content picker.
type	string	file, web_link	Indicates which type of items can be picked. Should be a comma seperated combination of file, folder or web_link.
sortBy	string	name	See the developer docs.
sortDirection	string	asc	See the developer docs.
extensions	Array<string>	[]	See the developer docs.
maxSelectable	number	Infinity	See the developer docs.
canUpload	boolean	true	See the developer docs.
canSetShareAccess	boolean	true	See the developer docs.
onCancel	function		Callback function for when the cancel button is pressed.
onChoose	function		Callback function for when the choose button is pressed.
isTouch	boolean		See the developer docs.
autoFocus	boolean		See the developer docs.
logoUrl	string		See the developer docs.
sharedLink	string		See the developer docs.
sharedLinkPassword	string		See the developer docs.
chooseButtonLabel	string		See the developer docs.
cancelButtonLabel	string		See the developer docs.
defaultView	string	files	See the developer docs.
responseFilter	function		See the developer docs.

Keyboard Shortcuts

See the developer docs.

Content Uploader (Documentation)

import React from 'react';
import { render } from 'react-dom';
import { ContentUploader } from 'box-ui-elements';
import messages from 'box-ui-elements/lib/i18n/en-US';
import 'box-ui-elements/dist/uploader.css';

const token = 'ACCESS_TOKEN';
const getLocalizedMessage = (id, replacements) =>
    messages[id].replace(/{\s*(\w+)\s*}/g, (match, key) => replacements[key]);

render(
    <ContentUploader
        token={token}
        getLocalizedMessage={getLocalizedMessage}
    />,
    document.querySelector('.container')
);

Props

Prop	Type	Default	Description
token*	string		See the developer docs.
getLocalizedMessage*	function(string, { [string]: string })		Function to get localized strings.
rootFolderId	string	0	The root folder for the content uploader.
onClose	function		Callback function for when the close button is pressed.
onComplete	function(Array<File>)		Callback function for when uploads are complete.
isTouch	boolean		See the developer docs.
logoUrl	string		See the developer docs.
sharedLink	string		See the developer docs.
sharedLinkPassword	string		See the developer docs.
responseFilter	function		See the developer docs.

Content Tree (Documentation)

import React from 'react';
import { render } from 'react-dom';
import { ContentTree } from 'box-ui-elements';
import messages from 'box-ui-elements/lib/i18n/en-US';
import 'box-ui-elements/dist/tree.css';

const token = 'ACCESS_TOKEN';
const getLocalizedMessage = (id, replacements) =>
    messages[id].replace(/{\s*(\w+)\s*}/g, (match, key) => replacements[key]);

render(
    <ContentTree
        token={token}
        getLocalizedMessage={getLocalizedMessage}
    />,
    document.querySelector('.container')
);

Props

Prop	Type	Default	Description
token*	string		See the developer docs.
getLocalizedMessage*	function(string, { [string]: string })		Function to get localized strings.
rootFolderId	string	0	The root folder for the content tree.
type	string	file, web_link, folder	Indicates which type of items show up in the tree. Should be a comma seperated combination of file, folder or web_link.
onClick	function(Folder|File|Web Link)		Callback function for when an item is clicked.
isTouch	boolean		See the developer docs.
autoFocus	boolean		See the developer docs.
logoUrl	string		See the developer docs.
sharedLink	string		See the developer docs.
sharedLinkPassword	string		See the developer docs.
responseFilter	function		See the developer docs.

Content Preview (Documentation)

The Box Content Preview has a slightly different interface than the other components. Instead of importing localizations like in the examples above, it requires a locale (defaults to en-US) to be passed in. This will automatically pull in the corresponding preview bundle and dynamically load it. It will also dynamically load the additional required CSS file needed for preview.

import React from 'react';
import { render } from 'react-dom';
import { ContentPreview } from 'box-ui-elements';
import 'box-ui-elements/dist/preview.css';

const token = 'ACCESS_TOKEN';
const fileId = 'FILE_ID';

render(
    <ContentPreview
        fileId={fileId}
        token={token}
    />,
    document.querySelector('.container')
);

Props

Prop	Type	Default	Description
token*	string		See the developer docs.
fileId*	string		The id of the file to preview.
locale	string	en-US	Locale for this component.
onLoad	function		Callback function for when a file preview loads.
collection	Array<string>	[]	See the developer docs.
showAnnotations	boolean	false	See the developer docs.
showDownload	boolean	false	See the developer docs.
header	string	light	See the developer docs.
logoUrl	string		See the developer docs.
sharedLink	string		See the developer docs.
sharedLinkPassword	string		See the developer docs.

Questions

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

Copyright and License

Copyright 2016-2017 Box, Inc. All Rights Reserved.

Licensed under the Box Software License Agreement v.20170516. You may not use this file except in compliance with the License. You may obtain a copy of the License at Box UI Elements Software License Agreement

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.