Chooser

Using the Chooser

The Chooser is the fastest way to get files from Dropbox into your web app. It’s a small JavaScript component that enables your app to get files from Dropbox without having to worry about the complexities of implementing a file browser, authentication, or managing uploads and storage.

This tutorial will guide you through everything you need to do to add the Chooser to your app and customize it to suit your use cases.

Demo

Click the button below to see the Chooser in action. This demo triggers a Chooser, which lets you choose a file from your Dropbox. Once a file is selected, the link is returned to the host website.

Setup

The first step in adding the Chooser to your app is to create an app. Using the Chooser doesn’t require production approval, so you can publish your integration to your users as soon as you’re ready.

When you create a Chooser app for the web, you’ll need to provide the domain names where your app is hosted. This lets us stop other websites from trying to impersonate your app.

Once you’ve created a new app, add the following JavaScript snippet to your HTML.

Replace YOUR_APP_KEY with the app key from your app’s page in the App Console.

<script type="text/javascript" src="https://www.dropbox.com/static/api/2/dropins.js" id="dropboxjs" data-app-key="YOUR_APP_KEY"></script>

Triggering the Chooser from JavaScript

There are two ways to trigger the Chooser on your website. To create the nice styled button you see in the demo above, you can use the following JavaScript:

var button = Dropbox.createChooseButton(options);
document.getElementById("container").appendChild(button);

If you prefer to design a custom button instead, you can trigger the Chooser directly from JavaScript using the following method:

Dropbox.choose(options);

Note that the Chooser opens in a pop-up window, so you should only call this function from within a user-triggered event handler such as a tap or click event. Otherwise, the pop-up will likely be blocked by the browser.

Security note: If you provide a custom windowName in the options, avoid using predictable or hardcoded values. Predictable window names can be pre-registered by attackers to hijack the browsing context. If you don’t provide a windowName, a cryptographically random one will be generated automatically.

Both methods take a single options parameter with the following fields:

options = {
    // Required. Called when a user selects an item in the Chooser.
    success: function(files) {
        alert("Here's the file link: " + files[0].link)
    },
    // Optional. Called when the user closes the dialog without selecting a file
    // and does not include any parameters.
    cancel: function() {
    },
    // Optional. "preview" (default) is a preview link to the document for sharing,
    // "direct" is an expiring link to download the contents of the file. For more
    // information about link types, see Link types below.
    linkType: "preview", // or "direct"
    // Optional. A value of false (default) limits selection to a single file, while
    // true enables multiple file selection.
    multiselect: false, // or true
    // Optional. This is a list of file extensions. If specified, the user will
    // only be able to select files with these extensions. You may also specify
    // file types, such as "video" or "images" in the list. For more information,
    // see File types below. By default, all extensions are allowed.
    extensions: ['.pdf', '.doc', '.docx'],
    // Optional. A value of false (default) limits selection to files,
    // while true allows the user to select both folders and files.
    // You cannot specify `linkType: "direct"` when using `folderselect: true`.
    folderselect: false, // or true
    // Optional. A limit on the size of each file that may be selected, in bytes.
    // If specified, the user will only be able to select files with size
    // less than or equal to this limit.
    // For the purposes of this option, folders have size zero.
    sizeLimit: 1024, // or any positive number
};

Handling the response

The files parameter in the above success callback function will be an array of file objects, each containing info about the selected file. If multiselect is false, the array will contain a single item. Each file object includes the following fields:

file = {
    // Unique ID for the file, compatible with Dropbox API v2.
    id: "id:...",
    // Name of the file.
    name: "filename.txt",
    // URL to access the file, which varies depending on the linkType specified when the
    // Chooser was triggered.
    link: "https://...",
    // Size of the file in bytes.
    bytes: 464,
    // URL to a 64x64px icon for the file based on the file's extension.
    icon: "https://...",
    // A thumbnail URL generated when the user selects images and videos.
    // If the user didn't select an image or video, no thumbnail will be included.
    thumbnailLink: "https://...?bounding_box=75&mode=fit",
    // Boolean, whether or not the file is actually a directory
    isDir: false,
};

The thumbnail link contains query string parameters that specify how the thumbnail is generated. By modifying these parameters, you can construct URLs for other sizes and modes of thumbnails:

• bounding_box Bounding box size for the thumbnail which must be one of the following values: 75 (default), 256, 800, 1280, 2048.
• mode One of the following resize modes:
  • fit default Shrink the original image maintaining the original aspect ratio until the entire image fits inside the bounding box.
  • crop Shrink the original image until its width or height fits in bounding box, then crop anything outside the bounding box.
  • fit_one_and_overflow Shrink the original image until its width or height fits into the bounding box but do not crop the left overs. The returned image will be larger than the bounding box. This is useful for situations where you need to use a square thumbnail but also want to use that image as a placeholder while you load a higher resolution version in the background.

Note, thumbnail links are temporary; links will expire after 4 hours.

Link types

The Chooser can be configured to return one of two link types.

• preview links are the default type of link returned by the Chooser. Preview links point to a human-friendly preview page of a file and are great for sharing. You can read more about links to Dropbox files in our Help Center. Note that users may disable this link at a later point if they choose.
• direct links point directly to the contents of the file and are useful for downloading the file itself. Unlike preview links, however, they will expire after four hours, so make sure to download the contents of the file immediately after the file is chosen. Direct links also support CORS, which allows you to read the file information directly in the browser using client-side JavaScript. These URLs should not be used to display content directly in the browser.

File types

In addition to individual file extensions, the extensions parameter in JavaScript allows the following file types: images, audio, video, documents, and text. Each file type corresponds to a list of individual file extensions, as defined below.

images

audio

video

documents

text

Supported browsers

Not all browsers support the Chooser. If a user’s browser doesn’t support the Chooser, we’ll gray out the button and show a warning message if you try to call Dropbox.choose(). You can check to see if the user’s browser is supported by calling Dropbox.isBrowserSupported().