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

<Frame>
  ![Multiple file upload component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/multiple-file-upload-overview.png)
</Frame>

***

## Overview

Unlike the [File Upload Button](./buttons#file-upload-button), which handles one file at a time via a button click, the Multiple File Upload component offers:

<CardGroup cols={3}>
  <Card title="Batch uploads" icon="files">
    Upload multiple files in a single request with individual validation per file
  </Card>

  <Card title="Drag and drop" icon="upload">
    Drag-and-drop zone with click-to-browse fallback
  </Card>

  <Card title="File management" icon="list-check">
    Preview selected files with name, size, and a remove option before uploading
  </Card>
</CardGroup>

**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={"system"}
{
  "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.
</Warning>

### 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](../../actions/upload-file-action) configured on the node. The SDK automatically populates `{actionName}TempFileIds` (a list of UUIDs) in the process instance params before triggering the action.

<Info>
  Starting with 5.5.0, the existing [File Upload Button](./buttons#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.
</Info>

***

## How it works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Documents persisted">
    The document plugin receives the bulk persist request, processes each file individually, and returns a response with per-file results (including partial success handling).
  </Step>
</Steps>

For the backend configuration details, see the [Upload File action](../../actions/upload-file-action) documentation and the [document upload scenario](../../../../platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document).

***

## Important behavior

<AccordionGroup>
  <Accordion title="Document type and storage" icon="folder-open">
    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>

  <Accordion title="Validation scope" icon="shield-check">
    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>

  <Accordion title="Upload feedback" icon="spinner">
    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>

  <Accordion title="File selection UX" icon="hand-pointer">
    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
  </Accordion>
</AccordionGroup>

***

## Theming

The Multiple File Upload component supports full theming through Theme Admin. The component is registered under `contentWeb → components → bulkFileUpload`.

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="Caption">
    | Token             | Description                        |
    | ----------------- | ---------------------------------- |
    | **Caption font**  | Font style for helper/caption text |
    | **Caption color** | Color for helper/caption text      |
  </Tab>
</Tabs>

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

<CardGroup cols={2}>
  <Card title="Upload file action" icon="upload" href="../../actions/upload-file-action">
    Configure the backend action for single and multi-file uploads
  </Card>

  <Card title="Uploading a new document" icon="file-circle-plus" href="../../../../platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document">
    End-to-end document upload scenario with the document plugin
  </Card>

  <Card title="File Upload Button" icon="file-arrow-up" href="./buttons#file-upload-button">
    Single-file upload button component
  </Card>

  <Card title="File preview" icon="eye" href="./file-preview">
    Display uploaded documents inline
  </Card>
</CardGroup>