> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.dropboxapi.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server.

# Embedder

The Embedder allows you to embed interactive previews of Dropbox files or folders inside an `<iframe>`. [Dropbox shared links](https://help.dropbox.com/files-folders/share/view-only-access) 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](https://help.dropbox.com/files-folders/share/banned-links).

## Setting up the Embedder

The first step to adding the Embedder is [creating a Dropbox app](https://www.dropbox.com/developers/apps/create). Using the embed component does not require [production approval](/dropbox-api/docs/developer-resources/developer-guide#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](https://www.dropbox.com/developers/apps). You can whitelist `localhost` if you’re developing locally:

![Component whitelist setting in Dropbox app settings](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/dropbox-api.docs.buildwithfern.com/fc29d8486039e8808defcf6e537a17ad9859252c93042840c98deac30ffd15c1/docs/assets/migrated/embedder/15a4ce0fab.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260912%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260912T073425Z&X-Amz-Expires=604800&X-Amz-Signature=e6017d8094f54cac2fd26c68607204a99857b04f00411fa2a40c7e1038da9804&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Once you’ve created an app, copy the JavaScript snippet below into your HTML and you’re ready to start building.

Replace `YOUR_APP_KEY` with the app key from your app in the App Console.

```html
<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](https://help.dropbox.com/files-folders/share/view-only-access) 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:

```html
<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%.

```html
<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:

```javascript
    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:

```javascript
  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()`.