File Upload

Let users pick or drag files into your application, upload them to configured storage, and expose the resulting file URLs and metadata for use in downstream actions and data sources.

Overview

The File Upload block accepts files via drag-and-drop or click-to-browse, uploads them to your workspace's configured cloud storage, and exposes the results as file descriptors — not raw bytes. You control which file types are allowed, how many files can be attached at once, a per-file size cap, who can access the stored files, and whether users can download them. An optional template file link and description add-on round out the UI.

The equivalent inside a Form block is the File Uploader form field, which participates in form submit, validation, and reset flows. Use the standalone block for page-level upload controls outside a form context.

Note: What gets stored? The file bytes go to cloud storage. What your logic receives is a descriptor object with id, name, url, size, mimeType, fileType (extension), sourceType, and source. Always read the URL or ID off this object; the binary file itself is never available in no-code expressions.

Block vs. Form Field

File Restrictions

Warning: Folder type is special: Adding Folder to Supported File Types turns on folder-picking mode (the user selects a whole directory), not a file extension filter. It strips "Folder" from the accept list and instead switches the native file picker into folder mode.

Access & File Visibility

The File Visibility setting controls who can open a stored file after upload. The available options depend on the workspace's cloud storage provider.

The app-level default for file visibility is set under App Settings → Advanced Settings → File Management. Individual block instances can override it. The visibility control on the block and on the form field both follow this hierarchy.

Allow Download (boolean, default true) — shows a download control in the uploaded file list. Turning it off hides the download action for users, but does not affect the url in state.

Add-ons

Appearance

Exposed State

Warning: During upload, url is a local blob — not a real link. While isUploaded is false, url points to a temporary browser blob preview useful for thumbnails, but useless as a shareable or storable link. Only after upload completes does isUploaded flip to true and url become the real backend download URL. Always gate any "save" or "submit" action on {{ id.isUploading }} being false.

Events & Methods

Events

Methods

File Uploader Form Field

When you need file upload as part of a form submission flow, use the FILE_UPLOADER form field instead of the standalone block. It lives inside a Form block and participates in validation, reset, and the submit payload.

Key differences from the standalone block

• Multiple vs. single mode: Controlled by Allow multiple files toggle. Single mode stores one file object; multiple mode stores an array.

• Validation: Maximum Files, Maximum File Size (MB), and Supported File Types live in the Validation section. Is Optional controls whether at least one file is required.

• Value shape: Single mode — {{ form.data.key }} is one object { id, name, url, sourceType, type }. Multiple mode — an array of such objects. Read .url or .id to pass to downstream queries.

• Events: On Change (fires when a file finishes uploading or is removed), On Focus, On Blur.

• Default value: Accepts an array of file objects for pre-filling the field. A dynamic default overwrites user-added files when the bound value changes.

File Uploader field properties

Behavior & Gotchas

The value is file descriptors, not raw binary data

What you get from {{ id.files }} is a list of descriptor objects — id, name, size, mime type, and a URL. There is no File object or byte stream available in no-code logic. To persist an upload, save the url or the storage id from the descriptor.

On File Uploaded fires once per batch, not once per file

Drop five files at once and the event fires a single time after the last file finishes, not five times. If you need per-file reactions, watch the {{ id.files }} array or its length changing rather than relying on the event.

Uploaded files are cleared when the block unmounts

When the block unmounts — a modal closes, the user navigates away — the file list is wiped. Files do not survive being hidden-by-unmount and re-shown. Read the files out before the modal closes or the user navigates.

You cannot pre-fill the block with existing files

The block always starts empty on every load. There is no content property that seeds it with previously uploaded files. To show files a record already has, use a separate display element (Image, attachment list, etc.); the File Upload block is for capturing new uploads only.

After the first file, the drop zone stops being click-to-upload

The empty state is fully clickable. Once one file is present, the card itself is no longer clickable. In multiple mode, an "Upload more" button stays available. In single mode, the user must remove the existing file before adding another.

"Only Me" visibility depends on the storage provider

The Only Me option is not offered on S3-backed storage. On S3 without public-upload enabled, the entire File Visibility control may be hidden and uploads default to Restricted. Public visibility also only truly serves files anonymously on providers that support it.

A rejected file does not block others in the same batch

Files that fail type/size checks show an inline error instead of uploading. Other valid files in the same batch still upload normally — a rejection is per-file, not per-batch.

Frequently Asked Questions

How do I access the URL of an uploaded file to save it to a record?

For the standalone block, read {{ id.files[0].url }} for the first file's URL after upload completes (check {{ id.isUploading }} is false first). For the form field in single mode, read {{ form.data.fieldKey.url }}. In multiple mode, loop over the array to collect each url. Note that during upload, url is a temporary browser blob — wait for isUploaded: true before saving.

Why does the On File Uploaded event only fire once even when I drop multiple files?

This is by design. The event fires once per batch — after all files in the current drop finish uploading, not once per individual file. If you need per-file reactions, watch {{ id.files }} array changes, or check each file's isUploaded flag reactively.

Can I restrict uploads to PDF and Word only, and prevent other types?

Yes. In File Restrictions → Supported File Types, select PDF and Word Document. Files of any other type will be rejected before upload with an inline error; valid files in the same drop still upload normally. The browser file picker will also be filtered to show only those types.

Why does my File Upload block reset when the containing modal closes?

When the block unmounts (a modal closing is a common trigger), the file list is automatically cleared. This is expected — the block stores files in transient memory, not persistent state. Always read {{ id.files }} (or submit the form) before closing the modal. Wire your "Save" action to run before the modal close action.

The file uploader form field shows an empty array in my data — why?

Removing the last file from the field stores an empty value (not an array), so "is this field filled" checks behave consistently in both single and multiple modes. Also confirm that your validation condition isn't treating an empty value as an array — when empty, the field holds undefined, not [].

Step-by-Step Examples