---
title: "File Management & Image Handling"
description: "Configure the file manager, image uploads, compression, and the built-in image editor, or replace the file manager with your own."
url: https://docs.topol.io/landing-page-editor/guide/file-management.html
---

# File Management & Image Handling

**Uploads land in Topol's storage unless you route them elsewhere, and these options are where that routing happens.** The file manager can keep its built-in flow with your preferences applied, talk to your backend through the [file management endpoints](#api-integration-for-file-management), or be replaced entirely with your own picker via `customFileManager`. Alongside the routing, a few options control image size limits, compression, and the built-in image editor.

## `customFileManager`

The `customFileManager` option (`boolean`, default `false`) bypasses the built-in file manager. Whenever a user attempts to upload or select a file, the editor triggers your `onOpenFileManager` callback instead, so your own file picker, storage workflow, or upload system takes over.

Note that `customFileManager` is a config option, while `onOpenFileManager` is a callback passed next to `config`. Hand the selected file URL back to the editor with the `chooseFile()` method:

```js
const LPE = LandingPageEditor({
  config: {
    authorize: { apiKey: "YOUR_API_KEY", userId: "user-123" },
    customFileManager: true,
  },
  onOpenFileManager: () => {
    // Open your custom file picker UI.
    // When the user selects a file, pass its URL back to the editor:
    openMyPicker((url) => LPE.chooseFile(url));
  },
});
LPE.render("#landing-page-editor");
```

**Cleaning up deleted files:** when users delete files or folders in the _built-in_ file manager, the editor fires the `onImageDelete` callback with the deleted items, so the deletion can be mirrored in your own storage:

```js
onImageDelete: ({ items }) => {
  // items: [{ name, type: "file" | "folder", path, url?, key }]
  items.forEach((item) => deleteFromMyStorage(item));
};
```

## `imageMaxSize`

The `imageMaxSize` option (`number`, default `2097152`, i.e. 2 MB) sets the maximum allowed image size in **bytes**. The editor validates files before upload and rejects any that exceed the limit:

```typescript
{
  imageMaxSize: 5242880 // 5 MB in bytes
}
```

For reference: 1 MB = 1048576 bytes, 5 MB = 5242880, 10 MB = 10485760.

## `imageCompressionOptions`

The `imageCompressionOptions` object configures automatic compression and resizing of uploaded images. When it is not set, compression and auto-resize are **enabled** with quality `0.95` (JPEG) / `0.8` (PNG). The properties:

-   `qualityJpeg` (`number`, **0 to 1**): JPEG compression quality (default: `0.95`)
-   `qualityPng` (`number`, **0 to 1**): PNG compression quality (default: `0.8`)
-   `enableAutoResize` (`boolean`): automatically resize large images (default: `true`)
-   `enableCompression` (`boolean`): enable image compression (default: `true`)

If `enableCompression` is `false`, both compression **and** auto-resize are disabled.

```typescript
{
  imageCompressionOptions: {
    qualityJpeg: 0.85,
    qualityPng: 0.8,
    enableAutoResize: true,
    enableCompression: true
  }
}
```

> **WARNING**
>
> Quality values use the 0 to 1 scale, not 0 to 100. A value outside that range - `85`, or `0` - is ignored and the default is kept, so the mistake is silent rather than harmful: quality simply stays at `0.95` / `0.8`. Always use decimals between 0 and 1.

## `imageEditorOptions`

The `imageEditorOptions` object configures the built-in image editor. Its one property, `hideControls` (`string[]`), removes the listed controls from the image editor UI:

```typescript
{
  imageEditorOptions: {
    hideControls: ["crop"]
  }
}
```

The image editor supports cropping, rotation, resizing, and basic adjustments. The editor itself cannot be disabled through an option - use `imageEditorOptions.hideControls` to hide individual tools instead.

## `fileManagerPreferences`

The `fileManagerPreferences` object adjusts the built-in file manager's UI defaults:

-   `defaultTilesView` (`boolean`): show files in tiles/grid view by default (vs. list view)
-   `hidePexelsIntegration` (`boolean`): hides the Pexels stock-image tab. Pexels is enabled by default.
-   `maxUploadingFiles` (`number`, positive integer): caps how many files can be selected and uploaded at once.

```typescript
{
  fileManagerPreferences: {
    defaultTilesView: true,
    hidePexelsIntegration: true,
    maxUploadingFiles: 5
  }
}
```

## `enableFileManagerInGif`

The `enableFileManagerInGif` option (`boolean`, default `false`) lets users pick a GIF from the file manager instead of only through the Giphy integration:

```typescript
{
  enableFileManagerInGif: true
}
```

## API Integration for File Management

The built-in File Manager UI connects directly to your infrastructure through a set of endpoints: listing files and folders, uploading images, creating folders, deleting files or folders, and saving edited images from the built-in image editor.

**All API responses must follow the expected structure to work correctly within the editor.**

> **WARNING**
>
> Before implementing the endpoints, check [how to work with API endpoints](https://docs.topol.io/landing-page-editor/guide/api.html).

### List Images & Folders

Used when the File Manager opens, to retrieve files and folders.

-   URL: `/{API.FOLDERS}`
-   Method: `GET`
-   Params: `path`, `hostname`, `userId`, `uuid`
-   Content-Type: `application/json`

> **The {key} placeholder**
>
> The `{key}` placeholder
>
> If your `FOLDERS` URL contains a `{key}` placeholder (e.g. `https://your-domain.com/folders/{key}`), the editor substitutes your API key into the path. Otherwise it appends the key as a `?key=<apiKey>` query parameter.

**Response:**

```json
[
  {
    "name": "filename.jpg",
    "date": "2024-12-01T14:23:00Z",
    "size": 512000,
    "path": "/path/",
    "type": "file",
    "extension": ".jpg",
    "url": "https://url-to-image.com/image.jpeg"
  },
  {
    "name": "holiday-images",
    "path": "/",
    "type": "folder"
  }
]
```

### Create New Folder

Used when a user adds a new folder in the File Manager.

-   URL: `/{API.FOLDERS}`
-   Method: `POST`
-   Content-Type: `application/json`

**Request:**

```json
{
  "name": "new-folder",
  "path": "/user-123/"
}
```

The `path` value is prefixed with `/{userId}` (the `authorize.userId`), so a folder created at the file manager root arrives as `"/user-123/"` rather than `"/"`. Identification values (`hostname`, `userId`, `uuid`, `id`, and the API `key` unless embedded in the URL) are sent as query parameters.

**Response:**

HTTP 2xx on success. The response body is not read by the editor.

### Delete Images or Folders

Used when a user deletes selected images or folders. The editor automatically appends `/delete` to the `FOLDERS` API path.

-   URL: `/{API.FOLDERS}/delete`
-   Method: `POST`
-   Content-Type: `application/json`

**Request:**

```json
[
  {
    "name": "filename.jpg",
    "type": "file",
    "path": "/"
  },
  {
    "name": "old-folder",
    "type": "folder",
    "path": "/",
    "key": null
  }
]
```

**Response:**

HTTP `200` or `204` on success (no body required).

### Image Upload

Used when a user uploads a file via the File Manager or drops an image onto an image block.

-   URL: `/{API.IMAGE_UPLOAD}`
-   Method: `POST`
-   Content-Type: `multipart/form-data`

**Request** (form fields):

| Field | Value |
| --- | --- |
| `image` | The file (binary) |
| `path` | Target folder path, e.g. `/` |
| `uuid` | The user ID |

**Response:**

```json
{
  "success": true,
  "url": "https://your-domain.com/images/uploaded-image.jpg",
  "name": "uploaded-image.jpg"
}
```

### Upload Image from Image Editor

Used when a user saves an image from the integrated image editor.

-   URL: `/{API.IMAGE_EDITOR_UPLOAD}`
-   Method: `POST`
-   Content-Type: `application/json`

> **WARNING**
>
> If `customFileManager` is enabled but `api.IMAGE_EDITOR_UPLOAD` is not set, saving from the image editor fails silently (the error only appears in the browser console). Always configure this endpoint when using a custom file manager.

**Request:**

```json
{
  "content": "data:image/png;base64,...",
  "filename": "edited-image.png"
}
```

**Response:**

```json
{
  "url": "https://your-domain.com/images/edited-image.png"
}
```