---
title: "File Component"
slug: "file-component"
tags: ["module-builder"]
updated: 2026-09-16T17:16:48Z
published: 2026-09-16T17:16:48Z
canonical: "docs.unqork.io/file-component"
---

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

# File Component

The File component lets end-users upload one or more files. It supports drag-and-drop, thumbnail previews, file size limits, file type restrictions, and automatic parsing of structured data files like CSV and Excel.

> **How to read settings tables**
> 
> The tables below describe each configurable option as it displays in the UnqorkAI platform. Values are formatted as follows: `inline code` — a value to type exactly as shown | **Bold** — a value selected from a drop-down, radio button, tab, or choice chip | **ON**/**OFF** — toggle state | ✓ — checkbox checked | ☐ — checkbox unchecked

## General Settings

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Property ID | `key` | Text input | `file` | The unique identifier for this component instance. |

## Display Settings

### Field Text

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Label Text | `label` | Text input | — | Identifies the component on the canvas and informs end-users what information is requested. |

### Contextual Help

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Tooltip | `description` | Text input | — | A brief description that displays when a cursor is positioned over the tooltip icon. |

### Default State Options

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Hide Field | `hidden` | Toggle | OFF | Hides the component from end-users but always displays in the Module Builder. |
| Allow Multiple Files Selection | `multiple` | Toggle | OFF | When set to **ON**, this setting lets end-users select multiple files in a single upload interaction. |
| Display Thumbnail Images or Icons | `image` | Toggle | OFF | When set to **ON**, this setting renders image files with a preview thumbnail. All other files display as text with a file icon. |
| ↳ Set Image Width | `imageSize` | Number input | `100` | The maximum width in pixels of the file preview or icon. Visible when **Display Thumbnail Images or Icons** is **ON**. |
| Drop Zone Label Text | `dropFilesLabel` | Text input | — | Text displayed inside the drag-and-drop area to guide end-users. |
| Starting Upload Message | `startingUploadMessage` | Text input | — | Text displayed when a file upload begins. |
| Browse Files Link Text | `browseLink` | Text input | — | The label on the button link that lets end-users browse their device for files. |
| Header for File Name Column | `fileNameLabel` | Text input | — | The column header label for the list of uploaded file names. |
| Header for File Size Column | `sizeLabel` | Text input | — | The column header label for the list of file sizes in kilobytes. |
| Drag and Drop Not Supported Message | `dragDropNotSupported` | Text input | — | Displays when the end-user's browser does not support drag-and-drop file upload. |

## Data Settings

### Data Storage

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Store Data in Database | `persistent` | Toggle | ON | When set to **ON**, this setting stores field values to the database when the module saves, end-users navigate between Panel components, or end-users navigate between workflow screens. Set to **OFF** to exclude this field from server-side submissions. |

> [!NOTE]
> Fields with **Store Data in Database** set to **OFF** are excluded from the Plug-In component's API responses and Unqork's built-in tracker. When using a Plug-In component to remote-execute a module, any component whose value must be included in the API response requires **Store Data in Database** set to **ON**.

> [!NOTE]
> Virus scans run against files stored in the UnqorkAI platform. Creators are responsible for scanning files stored in external services (for example, Google Drive, OneDrive, Dropbox).

## Actions Settings

### Triggers

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Post Add or Delete Trigger | `postTrigger` | Property ID | — | Triggers another component when a valid file is added or removed. |

## Validation Settings

### User Input

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Required | `validate.required` | Toggle | OFF | When set to **ON**, this setting requires at least one file to be uploaded before the module can be submitted. |
| Required Error Message | `errors.required` | Text input | `is required` | The error message displayed when no file has been uploaded. |

## Advanced Settings

### Additional Data Options

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Compress .jpg and .png Files | `compressFile` | Toggle | ON | When set to **ON**, this setting compresses image files to 1 MB on upload. Applies to `.jpg` and `.png` only. |
| Parse Excel Files with Multiple Tabs | `multiTabExcel` | Toggle | OFF | When set to **ON**, this setting parses all tabs of a multi-tab Excel file into a single JSON structure. |
| Parse Files on Upload | `parseOnUpload` | Toggle | OFF | When set to **ON**, this setting makes the Base64 representation of the file available on upload. |
| ↳ Parse Files Raw | `parseFilesRaw` | Toggle | OFF | When set to **ON**, this setting disables auto date formatting when parsing files. Applies to `.csv`, `.xls`, `.xlsx`, `.xlsm`, `.xlsb`, `.ods`. Visible when **Parse Files on Upload** is **ON**. |
| ↳ Delimiter | `delimiterChar` | Text input | — | The delimiter character used when parsing files. Visible when **Parse Files on Upload** is **ON**. |

### Additional Validation Options

#### Maximum File Size

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Set Maximum Size | `uqMaxFileSizeMB` | Number input | `10` | The maximum size in MB allowed for each individual file. Accepts values between 0 and 2048 MB. |
| File Size Helper Text | `maxFileSizeMessage` | Text input | `Maximum allowed file size (each file):` | Guidance text displayed to end-users about the file size limit. |
| File Size Error Message | `maxFileSizeWarning` | Text input | — | The error message displayed when an uploaded file exceeds the maximum size. |

#### Additional Styling

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Custom CSS Class | `customClass` | Text input | — | A custom CSS class for styling the component. |

#### Accepted File Formats

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Set File Formats to Accept | `filePattern` | Text input | — | The file types approved for upload. Separate each format with a comma (for example, `.jpg,.png`). Enter `*` to allow any file type. File type restrictions are client-side only and do not enforce a security boundary. For environment-wide file type restrictions, submit a [Support ticket](https://support.unqork.com). |
| File Format Error Message | `fileFormatErrorMessage` | Text input | `File type must be {{Types}}` | The error message displayed when an end-user selects a file type not listed in **Set File Formats to Accept**. |

## Operations Builder

This component supports the [Operations Builder](/unqorkai/docs/operations-builder) in Vega modules. When the module or panel runtime is set to **Vega (2.0)**, an **Event Handlers** section displays in the settings panel for configuring event-driven operations.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-09-16 | Added client-side security note to Set File Formats to Accept (EN-7918). |
| — | Initial publication. |

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

A Property ID is the unique field ID used by Unqork to track and link components in your module.

Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.

Rendering is the process of loading components and displaying the final result on the front-end screen.

The Number data type accepts integer or floating point values. The number data type does not use quotes around numerical values.

Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.

Base64 is an encoding and decoding technique used to convert binary data to an ASCII (American Standard for Information Interchange) text format.

A delimiter is a chracter or symbol that seperates words, data, or other characters. Use delimiters to mark the begining, or end of of value. Example delimiters include the comma ",", ampersand "&", or an empty space " ".

Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users.

Cumulative Layout Shift (CLS) measures how much elements in a webpage shift while using it. Some search engines use the CLS metric to rate a website's accessibility in their search rankings.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience.

The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience.