> ## 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. Available in both process-based screens and UI Flows.

### 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 | `"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/*`) | — | Yes |
| **Invalid file type message** | `invalidFileType` | Error shown when a file does not match accepted types | — | Yes |
| **Max files** | `maxFiles` | Maximum number of files allowed per upload | — | Yes |
| **Max files exceeded message** | `filesExceeded` | Error shown when the file count exceeds the limit | — | Yes |
| **Max files size** | `maxFilesSize` | Maximum total size of all files in bytes | — | Yes |
| **Files size exceeded message** | `filesSizeExceeded` | Error shown when total size exceeds the limit | — | 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 |
| - | - | - | - |
| **Show success** | `showSuccess` | Display a toast notification on successful upload | `false` |
| **Success message** | `successMessage` | Custom success toast text | `"Files successfully uploaded"` |
| **Show 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 type** | `loading` | Loading indicator style (`Overlay` or `None`) | `None` |
| **Loading message** | `loadingMessage` | Text displayed during the upload | `"Files are being uploaded..."` |

### Visibility

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

***

## Event handler configuration

The Multiple File Upload component only supports the **Upload** action type.

When configuring the event handler for this component, 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 **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 the upload completes, the component clears its state (file list), hides the loader, and shows a success or error toast (if configured).

> [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`.

> [tab] Drop zone
>
> | Token | Description |
> | - | - |
> | **Title font** | Font style for the drop zone heading |
> | **Title color** | Color for the drop zone heading |
> | **Subtitle font** | Font style for the subtitle text |
> | **Subtitle color** | Color for the subtitle text |
> | **Border width** | Drop zone border width (inherits from general) |
> | **Border 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 font** | Font style for the file name |
> | **File name color** | Color for the file name |
> | **File size font** | 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 font** | 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:

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