---
title: "Tiny Drive Plugin API"
description: "Description of the Tiny Drive plugin API"
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/introduction-to-tinydrive-apis/"
md_url: "https://www.tiny.cloud/docs/tinymce/5/introduction-to-tinydrive-apis/index.md"
version: "5"
last_updated: "2024-04-09T09:35:32Z"
tokens: 1549
---
Important This page documents TinyMCE 5. For new projects, Tiny recommends using the latest, most up-to-date version. [See TinyMCE 8 documentation](../../latest/introduction-to-tinydrive-apis/).
# Tiny Drive Plugin API

The Tiny Drive TinyMCE plugin has an API that enables access to Tiny Drive from your custom plugins or TinyMCE specific integration code. This API is available though the `editor.plugins.tinydrive` property.

## `tinydrive.pick`

The `tinydrive.pick` method enables you to pick files from Tiny Drive and get the meta data of those files returned in a promise. For a complete list of available settings to pass in to this method check the [Picker settings](#pickersettings) section in this page.

### File Picker Result Format

The `tinydrive.pick` API method will return a promise with object that has a `files` property. This `files` property is an array of files with the following properties.

#### name

The name of the selected file for example `my.jpg`.

#### size

The size in bytes of the selected file.

#### url

The url for the selected file would be in the following format: `https://drive.tiny.cloud/1/<your api key>/<file uuid>`

#### mdate

The modification date for the file in ISO 8601 format for example `2019-02-24T15:00:00Z`

### Interactive example: Using `tinydrive.pick`

**Example**

```js
tinymce.init({
  selector: 'textarea#drive-pick-example',
  height: 200,
  menubar: false,
  plugins: [
    'tinydrive link image media'
  ],
  toolbar: 'custom | insertfile | link image media',
  setup: function (editor) {
    editor.ui.registry.addButton('custom', {
      text: 'Custom pick',
      onAction: function () {
        editor.plugins.tinydrive.pick({
        }).then(function (result) {
          result.files.forEach(function (file) {
            var link = editor.dom.createHTML('a', { href: file.url }, editor.dom.encode(file.name));
            editor.insertContent(link);
          });
        });
      }
    });
  }
});
```

## `tinydrive.browse`

The `tinydrive.browse` method enables you to browse your files stored in Tiny Drive but without the possibility to pick them to be inserted. This might be useful if you want to use Tiny Drive as a generic file manager. It returns a promise but the promise will only resolve when the Tiny Drive dialog is closed by using the close button. For a complete list of available settings to pass in to this method check the [Picker settings](#pickersettings) section in this page.

### Interactive example: Using `tinydrive.browse`

**Example**

```js
tinymce.init({
  selector: 'textarea#drive-browse-example',
  height: 200,
  menubar: false,
  plugins: [
    'tinydrive link image media'
  ],
  toolbar: 'custom | insertfile | link image media',
  setup: function (editor) {
    editor.ui.registry.addButton('custom', {
      text: 'Custom browse',
      onAction: function () {
        editor.plugins.tinydrive.browse({
        }).then(function () {
          console.log('Tiny Drive dialog closed.');
        });
      }
    });
  }
});
```

## `tinydrive.upload`

The `tinydrive.upload` method enables directly upload blobs to your Tiny Drive storage. This can be useful when you want to store a file generated by your app.

### Interactive example: Using `tinydrive.upload`

**Example**

```js
tinymce.init({
  selector: 'textarea#drive-upload-example',
  height: 200,
  menubar: false,
  plugins: [
    'tinydrive link image media'
  ],
  toolbar: 'custom | insertfile | link image media',
  setup: function (editor) {
    editor.ui.registry.addButton('custom', {
      text: 'Custom upload',
      onAction: function () {
        editor.plugins.tinydrive.upload({
          path: '/hello',
          name: 'hello.txt',
          blob: new Blob(['Hello world!']),
          onprogress: function (progress) {
            console.log('upload progess', progress);
          }
        }).then(function (result) {
          var link = editor.dom.createHTML('a', { href: result.file.url }, editor.dom.encode(result.file.name));
          editor.insertContent(link);
        });
      }
    });
  }
});
```

## Picker settings

These settings are available for the [tinydrive.pick](#tinydrivepick) / [tinydrive.browse](#tinydrivebrowse) API methods.

### `filetypes`

This setting enables restricting what types of files you want do display based on [file type](../tinydrive-introduction/#filetypes) categories. For example if your app needs to insert images only then you can specify `['image']` in the file types array.

**Type:** `Array<string>`

#### Interactive example: Using `filetypes`

**Example**

```js
tinymce.init({
  selector: 'textarea#drive-pick-images-example',
  height: 200,
  menubar: false,
  plugins: [
    'tinydrive link image media'
  ],
  toolbar: 'custom | insertfile | link image media',
  setup: function (editor) {
    editor.ui.registry.addButton('custom', {
      text: 'Custom pick image',
      onAction: function () {
        editor.plugins.tinydrive.pick({
          filetypes: ['image']
        }).then(function (result) {
          result.files.forEach(function (file) {
            var img = editor.dom.createHTML('img', { src: file.url });
            editor.insertContent(img);
          });
        });
      }
    });
  }
});
```

### `max_image_dimension`

This setting enables constraining the width/height of uploaded images. When this is enabled any images with a higher width or height than the specified amount would be proportionally resized down to the specified maximum dimension.

**Type:** `Number`

#### Example: Using `max_image_dimension`

```js
tinydrive.pick({
  max_image_dimension: 1024
}).then(function (result) {
  console.log(result.files);
});
```

### Plugin API interfaces

Here is a complete API reference as TypeScript types for developers used to TypeScript syntax.

```ts
interface PluginApi {
  pick: (settings: PluginPickerApiSettings) => Promise<PickerResult>;
  browse: (settings: PluginPickerApiSettings) => Promise<void>;
  upload: (settings: PluginUploadApiSettings) => Promise<UploadResult>;
}

interface PluginPickerApiSettings {
  filetypes?: string[];
}

interface PluginUploadApiSettings {
  path?: string;
  name: string;
  blob: Blob;
  onprogress?: (details: UploadProgress) => void;
  max_image_dimension?: number;
}

interface DriveFile {
  url: string;
  size: number;
  name: string;
  type: string;
  mdate: string;
}

interface PickerResult {
  files: DriveFile[];
}

interface UploadProgress {
  loaded: number;
  total: number;
}

interface UploadResult {
  file: DriveFile;
}
```