Appearance

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.

If you want full control over how users upload and select files, Topol Plugin allows you to completely replace the built-in File Manager with your own custom solution.

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 ​

When a user clicks the “Choose a file” button in the editor (for example, when editing an image block), the onOpenFileManager() callback will be triggered:

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()
    }
  }
};

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

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");

This will insert the selected image into the currently active block or property field in the editor.

You must call this function after onOpenFileManager() is triggered. It is the only way to complete the file selection process and insert content into the editor.

Use Custom File Manager in the GIF block ​

By default, your custom file manager is wired up to the Image block only. The dedicated GIF block exposes a GIPHY tab and a Custom Source tab (manual URL input) - neither of which surfaces your custom file manager.

You can extend the Custom Source tab to also open your file manager by enabling the enableFileManagerInGif option:

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 Choose Image / Replace buttons next to the URL input. Clicking either button triggers the same onOpenFileManager() callback you already handle for images, and the URL returned via TopolPlugin.chooseFile() is written to the GIF block's src attribute.

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

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