File Input

Tips & examples

An upload action button decorated with a cloud-and-arrow icon that opens the standard browser file picker dialog, displaying a trash bin icon next to selected files for instant removal.

When to use

Allowing users to pick, upload, and manage binary files (documents, images, audio, video) inside form workflows.
Binding uploaded file references to backend database records while enforcing access permissions and file extension filters.

What you need

Disabled by default until a default_form is present on the page layout. Requires selecting an Element ID and a target Field Path to bind file uploads to form payloads.

Form-bound file path references, binary document attachments, media URLs, or storage object keys.
Data Source section attributes remain locked until a default_form is actively placed in the workspace hierarchy.

Examples

A document upload button bound to a user profile form field (['avatarImage']) with image/* browser filter restrictions.
An enterprise contract attachment control configured with ‘document’ type group permissions and a .pdf file filter.

Avoid

Using for simple text or markdown inputs where raw text content is entered directly rather than attached as a file.
Attempting to map Data Source form bindings before adding a parent default_form container onto the canvas layout.
Leaving the ‘Accept’ extension filter completely empty when expecting specific file formats like PDFs or images.

Pairs well with

Form — Provides the underlying form context, validation handling, and file path payload submission engine.

Properties

Editor properties

Configure these in the Application Designer property panel. Group headings mirror the editor where possible. Data Source is where the element gets its rows or field binding (a view/query, a connector operation, or a parent form field). References appear only for view-backed sources and map foreign-key ID columns to readable labels from another view.

Data Source

Element IDrequiredNumber or TextInside `dataSource`: Another element on the page whose data backs this field.
Default: none
Field PathrequiredList of Text or NumberInside `dataSource`: Path into the source element’s data (property segments).
Default: none

Advanced

Access Group NamerequiredText: Controls access role permissions governing who can view or download the uploaded file once stored in the system.
Default: public
Type Group NamerequiredText: Categorizes the uploaded file asset type in storage system registries.
Default: image
AcceptoptionalText: Browser-side file type filter string for the native upload picker (e.g., ‘image/*’ for images, ‘.pdf’ for PDFs, ‘.doc,.docx’ for Word files).
Example image/*,application/pdf
Default: none

Input

DisabledoptionalYes / no or Custom expression (yes/no): When true, the control cannot be edited.
Example false
Default: none

Sizing

Minimum size: 3 × 1 grid cells (width × height).

Translatable labels

label — Text label rendered on the face of the file upload trigger button alongside the upload icon.

Accessibility

Renders a accessible file input (<input type='file'>) with explicit ARIA label associations. Keyboard focus hits both the file trigger button and the trash removal icon.

Spacebar or Enter triggers the file chooser dialog.
Tab navigates between the upload button and the trash bin removal icon when a file is selected.

Expressions

Values you can read in expressions

Other parts of your app can read live values from this element in custom expressions:

elements.myFileInput.<property>

value string Current input value of this control. elements.myFileInput.value

When The stored path of the uploaded file — the value that is saved with the form. Empty until an upload finishes.

errors any Field-level validation errors after submit or blur. elements.myFileInput.errors

touched boolean Map of fields the user has interacted with. elements.myFileInput.touched

loading boolean True while data is loading from the server. elements.myFileInput.loading

When True while an upload is in progress. Disable the form's Save button with it so a record is not saved before its attachment exists.

metadata object Additional server metadata for the current result set. elements.myFileInput.metadata

file file The currently selected file, including its name and size. elements.myFileInput.file

uploadError string Error message if the last upload failed. elements.myFileInput.uploadError

metadataError string Error message if the file details could not be loaded. elements.myFileInput.metadataError

To use one of these, open the property you want to drive on the other element, switch it to expression mode in the Expression Editor, and enter:

1
elements.myFileInput.value

Replace myFileInput with this element’s unique id. Select the element in Application Designer and copy the id chip at the top of the right-hand property panel.

Composition

Where you can place it

Drag this element into one of these containers:

Placement notes

Form — Can be nested directly inside or placed alongside form layouts. When a form is linked as a data source, it transitions behavior from local state management to form-bound schema state tracking.

Sample configuration

Minimal example — required fields only ↕

1
2
3
4
5
6
{
  "config": {
    "accessGroupName": "accessGroupName",
    "typeGroupName": "typeGroupName"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "config": {
    "dataSource": {
      "elementId": "myElement",
      "fieldPath": [
        "fieldPath"
      ]
    },
    "defaultValue": "defaultValue",
    "disabled": false,
    "nullable": false,
    "accessGroupName": "accessGroupName",
    "typeGroupName": "typeGroupName",
    "accept": "accept",
    "fileName": "fileName"
  }
}

Ready-made setups

Form-Bound PDF Document Uploader ↕

Configures a 6x1 storage file upload button bound to a form field, filtering for PDF documents with access group permissions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "config": {
    "dataSource": {
      "elementId": "employeeOnboardingForm",
      "fieldPath": [
        "resumeDocumentPath"
      ]
    },
    "advanced": {
      "accessGroupName": "HR_Admins",
      "typeGroupName": "document",
      "accept": ".pdf"
    },
    "translation": {
      "label": "Upload Resume (PDF)"
    },
    "input": {
      "disabled": "@@expression: false"
    }
  }
}