Skip to content

box/box-ui-elements

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Project Status Styled With Prettier build status npm version

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.

Demo

The demo page has limited functionality https://opensource.box.com/box-ui-elements/

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.

IMPORTANT: The Preview UI Element listed below is a simple React wrapper for the preview library. The react component dynamically adds the preview library to the DOM via a <script> tag. The preview library assets will come from Box's CDN and currently there is no pure NPM version for it.

Installation

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

To prevent library duplication, the UI Elements require certain peer dependencies to be installed manually. For a list of required peer dependencies, see package.json.

Browser Support

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

Internationalization

The UI Elements use react-intl for internationalization. In order for the UI Elements to render properly, they need to be wrapped in an IntlProvider context and given a locale and translated messages to use. Each of the UI Element components below optionally take in a language property and a messages property which is then delegated to our internal IntlProvider. If either of these properties are not passed in, we do not use our internal IntlProvider and it is assumed that the parent react app (the react app that is importing in the UI Elements) has its own IntlProvider.

The language property is a string that can be one of en-AU, en-CA, en-GB, en-US, bn-IN, da-DK, de-DE, es-419, es-ES, fi-FI, fr-CA, fr-FR, hi-IN, 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 messages property is a map of message keys and translated strings. All the messages that the UI elements use can be found under the i18n folder. We distribute them as JS modules within the box-ui-elements npm package and they can be imported like any other module. We provide translated strings for all the langauges listed above.

For react-intl to work properly, locale data needs to be added via addlocaledata. They are all bundled inside the react-intl package inside node_modules. By default it uses the en locale but for any other locale you have to do similar to the following before rendering the component:

import { addLocaleData } from 'react-intl';
import frLocaleData from 'react-intl/locale-data/fr';
addLocaleData(frLocaleData);

The messages that are needed for the components can be imported from box-ui-elements/i18n/[LANGUAGE] package under node_modules. The code examples for each of the UI Elements below assume en-US and show how the US english messages are imported in.

Authentication

The Box UI Elements are designed to be agnostic of authentication type. They can be used for users with Box accounts (Managed Users) or those without (App Users), and 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, ContentOpenWith or ContentSidebar. Similarly, you can also import the ContentPickerPopup and ContentUploaderPopup which are popup versions for the Content Picker and Content Uploader, respectively.

Content Explorer (Documentation)

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

addLocaleData(enLocaleData);

render(
    <ContentExplorer
        token='ACCESS_TOKEN'
        language='en-US'
        messages={messages}
    />,
    document.querySelector('.container')
);

Props

Prop Type Default Description
token* string See the developer docs.
language string en-US See the Internationalization section
messages Map<string, string> See the Internationalization section
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.
initialPage number 1 See the developer docs.
initialPageSize number 50 See the developer docs.
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.
canCreateNewFolder 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.
requestInterceptor function See the developer docs.
responseInterceptor function See the developer docs.
contentPreviewProps Object {} Props that can be forwarded to the Content Preview UI Element. See them in the props section of Content Preview UI Element

Keyboard Shortcuts

See the developer docs.

Content Picker (Documentation)

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

addLocaleData(enLocaleData);

render(
    <ContentPicker
        token='ACCESS_TOKEN'
        language='en-US'
        messages={messages}
    />,
    document.querySelector('.container')
);

Props

Prop Type Default Description
token* string See the developer docs.
language string See the Internationalization section
messages Map<string, string> See the Internationalization section
rootFolderId string 0 The root folder for the content picker.
currentFolderId string The current folder shown for the content picker. This should be a sub folder to the root folder.
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.
initialPage number 1 See the developer docs.
initialPageSize number 50 See the developer docs.
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.
canCreateNewFolder 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.
requestInterceptor function See the developer docs.
responseInterceptor function See the developer docs.

Keyboard Shortcuts

See the developer docs.

Content Uploader (Documentation)

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

addLocaleData(enLocaleData);

render(
    <ContentUploader
        token='ACCESS_TOKEN'
        language='en-US'
        messages={messages}
    />,
    document.querySelector('.container')
);

Props

Prop Type Default Description
token* string See the developer docs.
language string See the Internationalization section
messages Map<string, string> See the Internationalization section
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.
onBeforeUpload function(Array<File>) Callback function for retrieving an item before it has uploaded on files only, doesn't work on folders
isTouch boolean See the developer docs.
logoUrl string See the developer docs.
sharedLink string See the developer docs.
sharedLinkPassword string See the developer docs.
requestInterceptor function See the developer docs.
responseInterceptor function See the developer docs.

Content Preview (Documentation)

IMPORTANT: The Content Preview UI Element (React component) works slightly different from the other UI Elements above. The React component is a wrapper for the Preview library. It also requires a langauge (defaults to en-US) to be passed in since the preview library bundles are localized. Providing a language will automatically pull in the corresponding preview.js bundle and dynamically load it by adding a script tag. It will also dynamically load the additional required preview.css file by adding a link tag.

import React from 'react';
import { render } from 'react-dom';
import { addLocaleData } from 'react-intl';
import enLocaleData from 'react-intl/locale-data/en';
import { ContentPreview } from 'box-ui-elements';
import messages from 'box-ui-elements/i18n/en-US';
import 'box-ui-elements/dist/preview.css';

addLocaleData(enLocaleData);

render(
    <ContentPreview
        fileId='FILE_ID'
        token='ACCESS_TOKEN'
        language='en-US'
        messages={messages}
    />,
    document.querySelector('.container')
);

Props

Prop Type Default Description
token* string See the developer docs.
fileId* string The id of the file to preview.
language string en-US See the Internationalization section
messages Map<string, string> See the Internationalization section
canDownload boolean true Visually hides the download and print buttons in the preview header if this is set to false. This prop has no effect when the file permission can_download is set to false.
collection Array<string> [] See the developer docs.
hasHeader boolean true Visually hides the preview header if this is set to false.
onClose function Callback function for when the file preview closes. If absent, the close button will not render in the header.
onLoad function Callback function for when a file preview loads.
requestInterceptor function See the developer docs.
responseInterceptor function See the developer docs.
sharedLink string See the developer docs.
sharedLinkPassword string See the developer docs.
showAnnotations boolean true See the developer docs.
contentSidebarProps Object {} Props that can be forwarded to the Content Sidebar UI Element. See them in the props section of Content Sidebar UI Element
contentOpenWithProps Object {} Props that can be forwarded to the Content Open With UI Element. See them in the props section of Content Open With UI Element

Note: Any other option listed here https://github.com/box/box-content-preview#parameters--options, which is also not listed or overriden above as a prop, will be passed on as-is to the Preview Library.

Content Open With (Documentation)

import React from 'react';
import { render } from 'react-dom';
import { addLocaleData } from 'react-intl';
import enLocaleData from 'react-intl/locale-data/en';
import { ContentOpenWith } from 'box-ui-elements';
import messages from 'box-ui-elements/i18n/en-US';
import 'box-ui-elements/dist/openwith.css';

addLocaleData(enLocaleData);

render(
    <ContentOpenWith
        fileId='FILE_ID'
        token='ACCESS_TOKEN'
        language='en-US'
        messages={messages}
    />,
    document.querySelector('.container')
);

Props

Prop Type Default Description
dropdownAlignment string left or right Determines the dropdown's alignment to the Open With button. 
boxToolsName string Box Tools This string will replace the name of Box Tools in the Install Box Tools to open this file on your desktop message. 
boxToolsInstallUrl string Box's install instructions This URL will be used instead of the default Box installation instructions which are linked in the Install Box Tools to open this file on your desktop message. 
onExecute Function A callback that executes when an integration invocation is attempted. 
token* string See the developer docs.
language string en-US See the Internationalization section
messages Map<string, string> See the Internationalization section
fileId* string The id of the file to preview.
requestInterceptor function See the developer docs.
responseInterceptor function See the developer docs.

Content Sidebar (Documentation)

import React from 'react';
import { render } from 'react-dom';
import { addLocaleData } from 'react-intl';
import enLocaleData from 'react-intl/locale-data/en';
import { ContentSidebar } from 'box-ui-elements';
import messages from 'box-ui-elements/i18n/en-US';
import 'box-ui-elements/dist/sidebar.css';

addLocaleData(enLocaleData);

render(
    <ContentSidebar
        fileId='FILE_ID'
        token='ACCESS_TOKEN'
        language='en-US'
        messages={messages}
    />,
    document.querySelector('.container')
);

Props

Prop Type Default Description
token* string See the developer docs.
language string en-US See the Internationalization section
messages Map<string, string> See the Internationalization section
fileId* string The id of the file to preview.
requestInterceptor function See the developer docs.
responseInterceptor function See the developer docs.
hasActivityFeed boolean false See the developer docs.
hasMetadata boolean false See the developer docs.
hasSkills boolean false See the developer docs.
detailsSidebarProps Object {} See below
activitySidebarProps Object {} See below
metadataSidebarProps Object {} See below
skillsSidebarProps Object {} See below

detailsSidebarProps

Prop Type Default Description
hasProperties boolean false See the developer docs.
hasAccessStats boolean false See the developer docs.
hasVersions boolean false See the developer docs.
hasNotices boolean false See the developer docs.

activitySidebarProps

Prop Type Default Description
onCommentCreate function See the developer docs.
onCommentDelete function See the developer docs.

metadataSidebarProps

Prop Type Default Description
tbd - - -

skillsSidebarProps

Prop Type Default Description
tbd - - -

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-present 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

https://developer.box.com/docs/box-sdk-license

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.