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

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:

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:

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.

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:

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.