---
title: "Custom File Manager"
description: "Replace the built-in File Manager with your own, so users pick files from the media library they already know."
url: https://docs.topol.io/email-editor/guide/custom-filemanager.html
---

# Custom File Manager

> **This feature is available with the Plugin for Business plan and higher.**
>
> If you're on the Plugin for Startup or Plugin Expansion plan, consider upgrading to access this feature. For more details, visit our [pricing page](https://topol.io/pricing) or contact support.

**Setting `customFileManager: true` replaces the built-in File Manager with a callback into your own UI.** The editor stops handling file selection and instead asks your application for a URL whenever a user wants to pick an image.

## Disable the built-in File Manager

To disable the default Topol File Manager, simply set the following option in your `TOPOL_OPTIONS` configuration:

```ts
customFileManager: true,
```

Once this is enabled, the editor will no longer handle file selection internally. Instead, it will rely on the custom callbacks you define, as described below.

## 1\. Handle File Manager trigger

Clicking **Insert** (or **Replace** on a field that already holds an image) triggers the `onOpenFileManager()` callback:

```ts
const TOPOL_OPTIONS = {
  customFileManager: true,
  callbacks: {
    onOpenFileManager() {
      // Open your custom file manager UI here
      // Let the user pick a file, then call TopolPlugin.chooseFile()
    }
  }
};
```

Use this to open a modal from your platform's existing media library, a third-party integration or a fully custom-built upload tool.

**The callback receives no arguments by design.** The editor remembers which field triggered it, including the row index inside repeating blocks, and routes the returned URL to the right place.

## 2\. Return the selected file

After the user selects a file from your custom interface, return the file to editor using the `TopolPlugin.chooseFile(selectedFileUrl)` method:

```ts
TopolPlugin.chooseFile("https://your-domain.com/uploads/image.png");
```

The method takes a single URL string. Calling it after `onOpenFileManager()` is the only way to complete the selection, since no other path writes the file back into the template.

## Where the custom file manager applies

The replacement is not limited to the Image block. Every surface below routes through the same `onOpenFileManager()` callback:

-   Image blocks
-   Section background images, including the Section settings panel
-   Carousel slides
-   Social network icons
-   Rating block segment values
-   Product and Custom API block items
-   Google Promotional Annotations
-   The GIF block, once opted in (see below)

Where the returned URL lands depends on the selection: an image inside a repeating block updates that row, and with **no block selected** it becomes the section's background image.

> **WARNING**
>
> `customFileManager: true` only replaces file _selection_; it does not cover saving an edited image from the built-in Image Editor. That save uploads through your `API.IMAGE_UPLOAD` endpoint (the same endpoint regular uploads use), so it must be configured, otherwise saving an edited image stops with an error in the console. See [Self-hosted Storage](https://docs.topol.io/email-editor/guide/self-hosted-storage.html).

## Use custom File Manager in the GIF block

The dedicated GIF block exposes a **GIPHY** tab and a **Custom Source** tab (manual URL input). Neither surfaces your custom file manager until you opt in with `enableFileManagerInGif`, which **requires `customFileManager: true` as well**:

```ts
const TOPOL_OPTIONS = {
  customFileManager: true,
  enableFileManagerInGif: true,
  callbacks: {
    onOpenFileManager() {
      // The same callback is reused for both Image and GIF blocks.
      // Open your custom file manager UI here, then call TopolPlugin.chooseFile()
      // with the selected GIF URL.
    },
  },
};
```

Once enabled, the GIF block's **Custom Source** tab renders **Insert** and **Replace** buttons next to the URL input. Either one triggers the same `onOpenFileManager()` callback, and the URL returned via `TopolPlugin.chooseFile()` is written to the GIF block's `src` attribute.

This option is opt-in for backwards compatibility, so existing integrations that rely on `customFileManager: true` see no file manager buttons in the GIF block until they set `enableFileManagerInGif: true`.

The built-in **Edit** and **Create new** actions stay hidden in the GIF block, because the Image Editor is raster-based and cannot process animated GIFs.