Using the Embedder

The Embedder allows you to embed interactive previews of Dropbox files or folders inside an <iframe>. Dropbox shared links are used as the data source for the embedded content. The embedded content respects the permissions and settings of the underlying shared link. Shared links are publicly accessible by default, but have settings to restrict access, such as to team members only.

The Embedder is a pre-built component; a small, built-by-Dropbox JavaScript library that allows your users to view and interact with Dropbox files and folders. By copying a snippet into their HTML, developers can generate embedded previews of Dropbox content.

Note that because embeds are based on shared links, the embedded content can be taken down if it exceeds the limits outlined in this help center article.

Setting up the Embedder

The first step to adding the Embedder is creating a Dropbox app. Using the embed component does not require production approval for your app. You can publish your integration to your users as soon as you’re ready.

In order to add the Embedder component to your app, you’ll need to provide the domain names where your app is hosted. This lets us stop others from trying to impersonate your app. You can whitelist your domain in your Dropbox app’s settings in the App Console. You can whitelist localhost if you’re developing locally:

Once you’ve created an app, use the pull-down menu below to select your Dropbox app and your app key will automatically be added to the sample code. Copy the JavaScript snippet to your HTML and you’re ready to start building.

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

Embedding Files or Folders using anchor tags

One way to embed content is using an anchor tag (<a>). Anchor tags with class=dropbox-embed and an href attribute set to a shared link will automatically expand the link into embedded content.

Here’s an example of an anchor tag using the embed component with a shared link to an image stored in Dropbox:

<a 
  href="https://www.dropbox.com/s/u0bdwmkjmqld9l2/dbx-supporting-distributed-work.gif?dl=0" 
  class="dropbox-embed"
></a>

And here's the file preview embedded on the page:

You can also set the height and width of the container element by using the data-height and data-width attributes. By default these values are set to 100%.

<a
  href="https://www.dropbox.com/s/u0bdwmkjmqld9l2/dbx-supporting-distributed-work.gif?dl=0"
  class="dropbox-embed"
  data-height="300px"
  data-width="600px"
></a>

This results in an embed with a specific container size:

Triggering the Embedder using JavaScript

Another way to use the Embedder is to embed content into a specific element using the JavaScript method Dropbox.embed(options, element). This approach can be particularly useful if you’re trying to create embedded content dynamically.

The options object must contain a link and may optionally define file settings and folder settings.

An example folder embed:

    var options = {
      // Shared link to Dropbox file
      link: "https://www.dropbox.com/sh/keptcjl08q3wsid/AACui966iXcXPbagCJ2py2L-a?dl=0",
      file: {
        // Sets the zoom mode for embedded files. Defaults to 'best'.
        zoom: "best" // or "fit"
      },
      folder: {
        // Sets the view mode for embedded folders. Defaults to 'list'.
        view: "list", // or "grid"
        headerSize: "normal" // or "small"
      }
    }
    Dropbox.embed(options, element);

By modifying these parameters, you can change the embedded content and the behavior of the Embedder:

• link - (required) - a Dropbox shared link to the content being embedded. Changing this link will update the embedded content.
• file - (optional) - a file options object used to configure embedded file behavior. May contain the following parameters:
  • zoom - (optional) - a string that sets the level of zoom for embedded files. May be set to the following values:
    • 'best' - (default) - sets the zoom mode to best, which sets the zoom of documents to the full width of the embed container. The zoom for other file content is set to the largest dimension (height or width) of the content being embedded.
    • 'fit' - sets the zoom mode to fit, which will automatically set the file’s zoom to the largest dimension of the embedded content. For documents, this mode sets the zoom to the largest dimension of the first page.
• folder - (optional) - a folder options object that contains settings to configure embedded folder behavior. May contain the following parameters:
  • view - (optional) - a string that sets the starting view mode for embedded folders, which may be set to one of the following values:
    • 'list' - (default) - starts folder in list view
    • 'grid' - starts folder in grid view
  • headerSize - (optional) - a string that sets the style of header to use for the embedded folder
    • 'normal' - (default) - use the default size header, ideal for medium- to large-sized containers
    • 'small' - use a smaller header, recommended for small-sized containers

The snippet above embeds a preview of a Dropbox folder in list view:

Removing the Embedder

The Dropbox.embed() function returns a reference to the Embedder that can be passed to the Dropbox.unmount() function to remove the Embedder from the document. This can be used to replace the Embedder with a new one in order to change the content, etc.

For example:

  const embed = Dropbox.embed(options, container);
  ...
  Dropbox.unmount(embed);

Supported files

The Embedder supports many types of files ranging from multi-page docs to images. Currently, the Embedder does not support audio or video.

Supported browsers

You can check whether a user’s browser is supported by calling Dropbox.isBrowserSupported().