Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Content Picker

Content Picker

The Box Content Picker UI Element allows developers to add support for selecting files and folders from Box in their desktop or mobile web application. The library fetches information about a specified folder through the Box API and renders the content in a folder view. Users can select files or folders and this content information is then passed to another part of the application.

Installation

Learn how to install Box UI elements either through NPM or the Box CDN.

Authentication

The UI Elements are designed in an authentication 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 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.

Learn about selecting an authentication method

Sample HTML

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>Box File Selection</title>

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

Demo

File Selection Demo

Folder Selection Demo

File Selection + Preview Demo

File Selection as a popup

Access Token

These demos may not fully function until you provide a valid access token. For testing purposes, you can use your temporary developer token. This will need to be updated under the JS tab in the demo.

API

const { FilePicker } = Box;
const filePicker = new FilePicker();

/**
 * Shows the file selection.
 *
 * @public
 * @param {String} folderId - The root folder id.
 * @param {String} accessToken - The API access token.
 * @param {Object|void} [options] - Optional options.
 * @return {void}
 */
filePicker.show(folderId, accessToken, options);

/**
 * Hides the file picker, removes all event listeners, and clears out the HTML.
 *
 * @public
 * @return {void}
 */
filePicker.hide();

/**
 * Clears out the internal in-memory cache for the file picker. This forces
 * items to be reloaded from the API.
 *
 * @public
 * @return {void}
 */
filePicker.clearCache();

/**
 * Adds an event listener to the file picker. 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}
 */
filePicker.addListener(eventName, listener);

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

/**
 * Removes all event listeners from the file picker.
 *
 * @public
 * @return {void}
 */
filePicker.removeAllListeners();

Parameters

ParameterTypeDescription
folderIdStringBox Folder ID. This will be the ID of the folder from which you want the content to be picked. If you want to use the Box All Files folder, then use 0 as the folderId.
accessTokenStringBox API access token to use. This should have read/write access to the folder above. The value passed in for the token is assumed to never expire while the explorer is visible.
optionsObjectOptional options. See below for details. For example: contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false}) would be used to hide the delete option.

Options

ParameterTypeDefaultDescription
containerStringdocument.bodyCSS selector of the container in which the content picker should be placed. Calling hide() will clear out this container.
sortByStringnameThe initial sort by option for the content list. Value should be either name or date.
sortDirectionStringASCThe initial sort direction option for the content list. Value should be either ASC or DESC.
logoUrlStringURL of custom logo to show in header. If this value is the string box then the box logo will show.
extensionsArray<string>[]Array of file extensions to be allowed for selection. for example ['doc', 'ppt']. Applicable only to the File Picker and not the Folder Picker. If any extensions are provided, only those will have the ability to be selected. An empty array signifies all the file extensions are allowed for selection.
maxSelectableNumberInfinityNumber of files or folders that can be selected. Specify 1 if you want only 1 file or folder selected.
canUploadBooleantrueVisually hides the upload option if this is set to false. Hiding the option alone will not prevent uploading unless the current folder permissions also set can_upload to false. This option has no effect when the folder permission can_upload is set to false.
canSetShareAccessBooleantrueVisually hides the sharing drop down select if set to false. Hiding the select drop down alone will not prevent changing the share access unless the folder item permissions also set can_set_share_access to false. This option has no effect when the folder item permission can_set_share_access is set to false.
canCreateNewFolderBooleantrueVisually hides the create new folder option. Hiding the option alone will not prevent creating a new folder unless the folder item permissions also set can_upload to false. This option has no effect when the folder item permission can_upload is set to false.
sharedLinkStringShared link URL, required if folder is shared and the access token doesn't belong to an owner or collaborator of the file.
sharedLinkPasswordStringShared link password, required if shared link has a password.
modalObjectWhen the modal attribute is specified, then the content pickers will not be created in-place. Instead a button will be created in the container and clicking this button will launch the content picker in a modal popup.
sizeStringundefinedIndicates to the content picker 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.
isTouchBooleanDefaults to the browser and device's default touch supportIndicates to the content explorer that it's is being rendered on a touch enabled device.
autoFocusBooleanfalseWhen set to true, the item grid will get focus on initial load.
defaultViewStringfilesValue should either be files or recents. When set to recents, by default you will see recent items instead of the regular file/folder structure.
chooseButtonLabelStringString to re-label the Choose button
cancelButtonLabelStringString to re-label the Cancel button
requestInterceptorFunctionFunction to intercept requests. For an example see this CodePen. Our underlying XHR library is axios.js and we follow a similar approach for interceptors.
responseInterceptorFunctionFunction to intercept responses. For an example see this CodePen. Our underlying XHR library is axios.js and we follow a similar approach for interceptors.
ParameterTypeDefaultDescription
buttonLabelStringLabel for the button
buttonClassNameStringBox Blue ButtonCSS class to decorate the button
modalClassNameStringCSS class to decorate the modal popup content
overlayClassNameStringCSS class to decorate the modal popup overlay

Events

Event NameEvent DataDescription
chooseArray<File | Web Link | Folder>Will be fired when the Choose button is pressed. Event data will be an array of Folder Object or File Object or Web Link object depending upon whether it was a file selection or folder selection.
cancelWill be fired when the Cancel button is pressed

Keyboard Shortcuts

When the item grid has focus, either manually by clicking on it or programmatically via javascript or via the above mentioned autoFocus prop, the following keyboard shortcuts will work if their corresponding operations are applicable and allowed.

KeyAction
Arrow UpPrevious item row
Arrow DownNext item row
Ctrl/Cmd + Arrow UpFirst item row
Ctrl/Cmd + Arrow DownLast item row
/Search
Shift + XSelect an item row
EnterOpen the selected item
g then fNavigates to the root folder
g then uUpload to the current folder
g then bFocuses the root folder breadcrumb
g then sShows the selected items
g then xCancel
g then cChoose
g then rRecent items

Scopes

If your application requires the end user to only be able to access a subset of the Content Picker functionality, you can use Downscoping to appropriately downscope the Access 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 Picker.

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

Scope NamePermissions granted
base_pickerAllows access to content in the folder tree based on user/file/token permissions

Feature Scopes

Scope NamePermissions granted
item_shareAllows sharing of resource specified under "resource" of the Token Exchange request.
item_uploadAllows upload in the content picker

Sample Scenarios

ScenarioScopes
User wants to only navigate a folder structure and pick a file / folderbase_picker
User wants to navigate a folder structure, pick a file / folder and also set access levelbase_picker + item_share
User wants to navigate a folder structure, pick a file / folder and also upload a file / folderbase_picker + item_upload
User should be able to navigate a folder structure and pick a file / folder, upload a file / folder, and also set access level for a file/folderbase_picker + item_share + item_upload