Content Picker

Guides Embed Box UI Elements Content Picker

Required Guides

GuideInstallation

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.

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

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

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

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.

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();

Parameter	Type	Description
`folderId`	String	Box 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`.
`accessToken`	String	Box 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.
`options`	Object	Optional options. See below for details. For example: `contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})` would be used to hide the delete option.

Parameter	Type	Default	Description
`container`	`String`	`document.body`	CSS selector of the container in which the content picker should be placed. Calling hide() will clear out this container.
`sortBy`	`String`	`name`	The initial sort by option for the content list. Value should be either name or `date`.
`sortDirection`	`String`	`ASC`	The initial sort direction option for the content list. Value should be either `ASC` or `DESC`.
`logoUrl`	`String`		URL of custom logo to show in header. If this value is the string box then the box logo will show.
`extensions`	`Array<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.
`maxSelectable`	`Number`	`Infinity`	Number of files or folders that can be selected. Specify 1 if you want only 1 file or folder selected.
`canUpload`	`Boolean`	`true`	Visually 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`.
`canSetShareAccess`	`Boolean`	`true`	Visually 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`.
`canCreateNewFolder`	`Boolean`	`true`	Visually 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.
`sharedLink`	`String`		Shared link URL, required if folder is shared and the access token doesn't belong to an owner or collaborator of the file.
`sharedLinkPassword`	`String`		Shared link password, required if shared link has a password.
`modal`	`Object`		When 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.
`size`	`String`	`undefined`	Indicates 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.
`isTouch`	Boolean	Defaults to the browser and device's default touch support	Indicates to the content explorer that it's is being rendered on a touch enabled device.
`autoFocus`	`Boolean`	`false`	When set to `true`, the item grid will get focus on initial load.
`defaultView`	String	`files`	Value should either be `files` or `recents`. When set to `recents`, by default you will see recent items instead of the regular file/folder structure.
`chooseButtonLabel`	`String`		String to re-label the Choose button
`cancelButtonLabel`	`String`		String to re-label the Cancel button
`requestInterceptor`	`Function`		Function to intercept requests. For an example see this CodePen. Our underlying XHR library is `axios.js` and we follow a similar approach for interceptors.
`responseInterceptor`	`Function`		Function to intercept responses. For an example see this CodePen. Our underlying XHR library is `axios.js` and we follow a similar approach for interceptors.

Parameter	Type	Default	Description
`buttonLabel`	`String`		Label for the button
`buttonClassName`	`String`	Box Blue Button	CSS class to decorate the button
`modalClassName`	`String`		CSS class to decorate the modal popup content
`overlayClassName`	`String`		CSS class to decorate the modal popup overlay

Event Name	Event Data	Description
`choose`	`Array<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.
`cancel`		Will be fired when the Cancel button is pressed

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.

Key	Action
`Arrow Up`	Previous item row
`Arrow Down`	Next item row
`Ctrl/Cmd + Arrow Up`	First item row
`Ctrl/Cmd + Arrow Down`	Last item row
`/`	Search
`Shift + X`	Select an item row
`Enter`	Open the selected item
`g then f`	Navigates to the root folder
`g then u`	Upload to the current folder
`g then b`	Focuses the root folder breadcrumb
`g then s`	Shows the selected items
`g then x`	Cancel
`g then c`	Choose
`g then r`	Recent items

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 Name	Permissions granted
`base_picker`	Allows access to content in the folder tree based on user/file/token permissions

Scope Name	Permissions granted
`item_share`	Allows sharing of resource specified under "resource" of the Token Exchange request.
`item_upload`	Allows upload in the content picker

Scenario	Scopes
User wants to only navigate a folder structure and pick a file / folder	`base_picker`
User wants to navigate a folder structure, pick a file / folder and also set access level	`base_picker` + `item_share`
User wants to navigate a folder structure, pick a file / folder and also upload a file / folder	`base_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/folder	`base_picker` + `item_share` + `item_upload`

You can expand the actions in the More Options menu for files and folders in Content Explorer and Content Picker. Your custom options show when user clicks the ellipsis button.

To customize the More Options menu, pass an array of custom actions to itemActions.

contentExplorer.show(configData.FOLDER_ID, configData.ACCESS_TOKEN, {
    container: ".container",
    itemActions: customActions,
});

The array can include multiple actions. The action object should include the label, and the onAction callback function. You can filter the custom actions to appear only on a specific item type, by passing the file or folder value. The filter value is used for advanced filtering, for example by a specific file extension:

const customActions = [
    {
        label: "Preview in New Window",
        onAction: (item) => alert('action ' + item),
        type: 'file',
    },
    {
        label: "Open in Box.com",
        onAction: (item) => window.open("https://app.box.com"),
    },
    {
        label: "Export",
        onAction: (item) => console.log('action ' + item),
        filter: (item) => item.extension?.toLowerCase() === 'pdf',
    },
];

See the implemented examples in CodePen:

Related Guides

GuideUI Elements

Content Picker

Required Guides

Content Picker

Installation

Authentication

Sample HTML

Demo

File Selection Demo

Folder Selection Demo

File Selection + Preview Demo

Access Token

API

Parameters

Options

Events

Keyboard Shortcuts

Scopes

Feature Scopes

Sample Scenarios

Custom actions

Related Guides