Overview
The controlMediaUploads action gives you direct control over the upload lifecycle managed by a File Upload or Camera block. By default, these blocks begin uploading as soon as the user selects files. This action lets you override that behaviour — holding files in a queue until the user explicitly clicks "Upload All", retrying failed uploads, or cancelling uploads that are no longer needed.
The action returns a queue status snapshot that you can use to update a progress indicator or enable/disable related buttons.
Parameters
| Parameter | Type | Required | Default | Description |
| blockRef | string | Required (required) | — | Block ID of the File Upload or Camera block whose upload queue to control. The block must have Auto Upload disabled in its settings for pause/resume to have any effect. If the block doesn't exist, the action is a silent no-op. |
| operation | "start" | "pause" | "resume" | "cancel" | "clearQueue" | Required (required) | — | start — begins uploading all pending files in the queue.
pause — suspends the current upload mid-stream (if the server supports range requests) or after the current file completes.
resume — resumes a paused upload from where it stopped.
cancel — aborts all active uploads; files matching filter are removed from the queue.
clearQueue — removes files from the queue without cancelling active uploads. Combine with filter: "failed" to remove only errored files. |
| filter | "all" | "pending" | "failed" | Optional (optional) | "all" | Scopes the operation to a subset of the queue. pending targets files waiting to upload. failed targets files in an error state. all targets every file in the queue. Ignored by start and resume. |
Return Value — Upload Queue Status
The action resolves with a queueStatus object. Store it in a page variable to drive progress indicators:
| Field | Type | Description |
| totalFiles | number | Total files in the queue (all states). |
| pendingCount | number | Files waiting to start. |
| uploadingCount | number | Files currently transferring. |
| completedCount | number | Successfully uploaded files. |
| failedCount | number | Files that encountered an error. |
| totalBytes | number | Combined size of all files in bytes. |
| uploadedBytes | number | Bytes transferred so far across all files. |
| progressPercent | number | Overall progress 0–100. |
Step-by-Step Usage Guide
Disable auto-upload on the File Upload block: Select the File Upload block, open Settings → Upload Behaviour, and turn off Auto Upload on Select. Files will now queue without transferring.
Add Upload All and Retry Failed buttons: Add two buttons to the page: "Upload All" and "Retry Failed". Bind "Upload All" to a
startoperation; bind "Retry Failed" to astartoperation scoped withfilter: "failed"on a re-queue action, thenstartagain. Conditionally hide "Retry Failed" when{{ b_fileUpload.state.failedCount === 0 }}.Show a progress bar: Bind a Progress Bar block's value to
{{ b_fileUpload.state.uploadProgress }}(the block's built-in progress variable). Alternatively, store the return value ofcontrolMediaUploadsand readqueueStatus.progressPercent.Handle completion: Listen to the File Upload block's
onAllUploadsCompleteevent to fire subsequent actions — saving a record, showing a success notification, or navigating away.
Examples
Start uploading all pending files
{ "actionType": "controlMediaUploads", "payload": { "blockRef": "b_documentUploader", "operation": "start", "filter": "pending" } }
Retry only failed uploads
// Step 1: Clear failed items from queue to reset their state { "actionType": "controlMediaUploads", "payload": { "blockRef": "b_documentUploader", "operation": "clearQueue", "filter": "failed" } } // Step 2: Re-add and start (user re-selects files, or use a stored file list) { "actionType": "controlMediaUploads", "payload": { "blockRef": "b_documentUploader", "operation": "start" } }
Cancel all active uploads and clear the queue
{ "actionType": "controlMediaUploads", "payload": { "blockRef": "b_documentUploader", "operation": "cancel", "filter": "all" } }
Warning: Pause support depends on the upload endpoint. The pause operation sends an HTTP request abort signal to the in-progress upload. Whether the server supports resuming from a byte offset depends on your storage backend (S3 multipart, TUS protocol, etc.). Without server-side support, resume will re-upload the entire file from the beginning.