> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiple file upload

> A drag-and-drop upload component that lets users select and upload multiple files in a single action.

The Multiple File Upload component provides a drag-and-drop area where users can select multiple files and upload them in a single request. It is purpose-built for workflows that require batch document submission, such as onboarding packets, supporting evidence, or multi-page scans.

![Multiple File Upload component with two selected files and the Upload Files and Remove Files buttons](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/18b-multiple-file-upload-selected.png)

***

## Overview

Unlike the [File Upload Button](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/buttons.md#file-upload-button), which handles one file at a time via a button click, the Multiple File Upload component offers:

> [card] Batch uploads
>
> Upload multiple files in a single request with individual validation per file

> [card] Drag and drop
>
> Drag-and-drop zone with click-to-browse fallback

> [card] File management
>
> Preview selected files with name, size, and a remove option before uploading

**Platform availability:** React SDK (web): since 5.5.0. Angular SDK (web): since 5.8.0. The iOS and Android SDKs also render the component. Available in both process-based screens and UI Flows.

On iOS and Android, the **Reset label** field is not shown, and the component uses mobile defaults: the title `Upload Files`, the subtitle `Browse files or take a picture`, and the button labels `Browse` and `Upload`.

### UI Flow upload flow

When the component is bound to a UI Flow upload action:

1. The SDK uploads the selected files to the temp-file store via `POST /document/internal/wks/{workspaceId}/temp-files/upload-multiple` (multipart, document-plugin).
2. The SDK calls `POST /api/runtime/wks/{workspaceId}/appId/{appId}/ui-flow/{uiFlowSessionId}/upload-multiple` (process-engine) with the list of returned temp-file IDs. The 200 response returns a server-generated `uploadBatchId`.
3. process-engine sends a single bulk command to document-plugin; document-plugin persists each file in the session.
4. The SDK receives one SSE frame (`eventType=UI_FLOW_FILE_UPLOAD_MULTIPLE`, `namespace=uploadBatchId`) carrying the per-file results.
5. The per-file results are written to the action's `responseKey` as a list under the UI Flow session variables.

**UI Flow response shape:**

```json theme={"dark"}
{
  "documents": [
    { "uploadResponseId": "...", "fileName": "...", "fileSize": 123, "errorMessage": null }
  ]
}
```

The UI Flow per-file shape (`UiFlowUploadResponse`) is a subset of the process-based upload response. It omits `customId`, `fileId`, `documentType`, `documentLabel`, and `status`, which are not meaningful for session-scoped uploads.

***

## Component properties

The following properties are available in the Multiple File Upload configuration panel:

### Display

| Property | Key | Description | Default |
| - | - | - | - |
| **Title** | `title` | Heading displayed in the drop zone | `"Drag & drop your files here"` |
| **Subtitle** | `subtitle` | Supporting text below the title | `"or click to browse your files"` |
| **Browse label** | `browseLabel` | Text on the browse button | `"Browse Files"` |
| **Upload label** | `uploadLabel` | Text on the upload action button | `"Upload Files"` |
| **Reset label** | `resetLabel` | Text on the remove/reset button (web only) | `"Remove Files"` |

### Validation

| Property | Key | Description | Default | Required |
| - | - | - | - | - |
| **Accepted file types** | `accept` | Comma-separated MIME types, extensions, or wildcards (e.g., `png`, `application/pdf`, `image/*`) | None | Yes |
| **Invalid file message** | `invalidFileType` | Error shown when a file does not match accepted types | None | Yes |
| **Max number of files** | `maxFiles` | Maximum number of files allowed per upload | None | Yes |
| **Max files error message** | `filesExceeded` | Error shown when the file count exceeds the limit | None | Yes |
| **Max files size (in bytes)** | `maxFilesSize` | Maximum total size of all files in bytes | None | Yes |
| **Files size error message** | `filesSizeExceeded` | Error shown when total size exceeds the limit | None | Yes |

> [!WARNING]
>
> All validation properties are required. You must configure accepted file types, max file count, and max file size along with their corresponding error messages.

### Feedback

| Property | Key | Description | Default |
| - | - | - | - |
| **Toast notification on success** | `showSuccess` | Display a toast notification on successful upload | `false` |
| **Success message** | `successMessage` | Custom success toast text | `"Files successfully uploaded"` |
| **Toast notification on error** | `showError` | Display a toast notification on upload failure | `false` |
| **Error message** | `errorMessage` | Custom error toast text | `"There was an error with the upload"` |
| **Loading behavior** | `loading` | Loading indicator style (`Overlay` or `None`) | `None` |
| **Loading message** | `loadingMessage` | Text displayed during the upload | `"Files are being uploaded..."` |

The message fields start empty. The Designer fills in the default text when you turn on **Toast notification on success** or **Toast notification on error**, or set **Loading behavior** to **Overlay**, while the matching message field is still empty.

### Visibility

Set these conditions in the **Expressions** section of the component settings.

| Property | Key | Description |
| - | - | - |
| **Hide condition** | `hide` | Expression that hides the component when it evaluates to `true` |
| **Disable condition** | `disabled` | Expression that disables the component when it evaluates to `true` |

***

## Event handler configuration

In a process user task, the Multiple File Upload component offers the **Upload** and **Run local script** action types. In a UI Flow, the event handler offers **Run local script**, **Upload**, **Start process**, **Start workflow**, **External**, **Navigate to**, and **Dismiss**. When the UI Flow page contains a **Chat** component or has a global chat assigned, it also offers **Conversation reply trigger**.

When configuring the event handler for this component in a process user task, set:

* **Event type**: `CLICK`
* **Action type**: `Upload`

This links the component to an [Upload File action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/upload-file-action.md) configured on the node. The SDK automatically populates `{actionName}TempFileIds` (a list of UUIDs) in the process instance params before triggering the action.

> [!NOTE]
>
> Starting with 5.5.0, the existing [File Upload Button](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/buttons.md#file-upload-button) is also adjusted so that, in a process user task, **Upload** is its only selectable action type (matching this component). It continues to work with the single-file path (`{actionName}TempFileId`). Both components can coexist in the same process.

***

## How it works

**1. User selects files**

The user drags files into the drop zone or clicks **Browse Files** to select them. Each file is validated against the configured accepted types, max files count, and max file size.

**2. Files uploaded to temporary storage**

When the user clicks **Upload Files**, the SDK sends all selected files in a single `multipart/form-data` request to the document plugin's bulk temp upload endpoint. The response returns a list of temporary file IDs.

**3. Process action triggered**

The SDK populates `{actionName}TempFileIds` with the list of temp file IDs and triggers the Upload File action. The process engine detects the list key and routes the request through the bulk Kafka path.

**4. Documents persisted**

The document plugin receives the bulk persist request on `ai.flowx.plugin.document.trigger.persist.document.bulk.v1`, processes each file individually, and returns a response with per-file results (including partial success handling) on `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1`. Each file in the reply has its own `downloadPath`.

For the backend configuration details, see the [Upload File action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/upload-file-action.md) documentation and the [document upload scenario](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document.md). To show each uploaded file on the same user task, see [Preview files in a collection](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md#preview-files-in-a-collection).

***

## Important behavior

> [accordion] Document type and storage
>
> All files uploaded through this component share the same `customId` and use `documentType=BULK` with `shouldOverride=false`. This means:
>
> * Multiple files accumulate under the same `customId`. They are stored as separate documents, not as a single archive
> * **Re-uploading does not replace previous files**: it adds new ones alongside the existing documents
> * If you need to replace previously uploaded files, you must delete them separately before re-uploading

> [accordion] Action order on the node
>
> The process engine rejects the Upload File action while a mandatory action placed above it on the same node hasn't run. In the node's **Actions** list, place the Upload File action above mandatory manual actions such as the `saveData` action the user task creates.

> [accordion] Validation scope
>
> Validation runs **client-side before upload**:
>
> * **File type**: validated per file against the `accept` property
> * **File count**: validated against `maxFiles` (total selected files)
> * **Total size**: validated against `maxFilesSize` (sum of all file sizes)
>
> There is no per-file size limit in this component. Only the total size across all files is checked.

> [accordion] Upload feedback
>
> The component provides an overall loading state (overlay or none) during the upload. Individual per-file progress indicators are not available: the upload is treated as a single batch operation.
>
> After a successful upload, the component clears the file list. If the upload fails, the selected files stay in the list so the user can retry.

> [accordion] File selection UX
>
> Users can add files incrementally:
>
> * Drag and drop files into the zone multiple times
> * Click **Browse Files** multiple times to add more
> * Each selected file appears as a card showing file name and size
> * Individual files can be removed with the delete button before uploading
> * The **Remove Files** button clears all selected files at once

***

## Theming

The Multiple File Upload component supports full theming through Theme Admin. The component is registered under `contentWeb → components → bulkFileUpload`. In Theme Admin, its options are in the **Common Properties** and **Icons** sections. The tabs below group the **Common Properties** options by the part of the component they style.

> [tab] Drop zone
>
> | Token | Description |
> | - | - |
> | **Title style** | Font style for the drop zone heading |
> | **Title color** | Color for the drop zone heading |
> | **Subtitle style** | Font style for the subtitle text |
> | **Subtitle color** | Color for the subtitle text |
> | **Border Width** | Drop zone border width (inherits from general) |
> | **Radius** | Drop zone corner radius (inherits from general) |
> | **Border color** | Drop zone border color |
> | **Background color** | Drop zone background |
> | **Shadow** | Drop zone shadow |

> [tab] File items
>
> | Token | Description |
> | - | - |
> | **File name style** | Font style for the file name |
> | **File name color** | Color for the file name |
> | **File size style** | Font style for the file size text |
> | **File size color** | Color for the file size text |
> | **File Border Width** | Border width for individual file rows |
> | **File Border Radius** | Corner radius for individual file rows |
> | **File border color** | Border color for individual file rows |

> [tab] Caption
>
> | Token | Description |
> | - | - |
> | **Caption style** | Font style for helper/caption text |
> | **Caption color** | Color for helper/caption text |

### Icons

The component uses three system icons that are included automatically via CMS migration. You can replace them in Theme Admin, in the **Icons** section: **Title Icon**, **Document Icon**, and **Delete Icon**.

| Icon key | Description |
| - | - |
| `sys_BFUTitle` | Icon displayed in the drop zone header |
| `sys_BFUDocument` | Icon displayed next to each file in the list |
| `sys_BFUDelete` | Icon for the delete/remove button on each file |

### Substitution tags

The component also registers system substitution tags for localization and accessibility:

| Tag code | English | Romanian |
| - | - | - |
| `sys_bfu_max_files_size` | Maximum files size: | Dimensiune maximă a fișierelor: |
| `sys_a11y_bfu_drop_files` | Drop files | Plasează fișierele |
| `sys_a11y_bfu_delete_file` | Delete file | Șterge fișier |

These tags are automatically available after CMS migration and can be customized per language in the CMS.

***

## Related resources

> [card] [Upload file action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/upload-file-action.md)
>
> Configure the backend action for single and multi-file uploads

> [card] [Uploading a new document](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document.md)
>
> End-to-end document upload scenario with the document plugin

> [card] [File Upload Button](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/buttons.md#file-upload-button)
>
> Single-file upload button component

> [card] [File preview](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md)
>
> Display uploaded documents inline


## Related topics

- [Upload file action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/upload-file-action.md)
- [File download](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download.md)
- [File preview](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md)
- [Buttons](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/buttons.md)
- [FlowX.AI 5.6.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.