Files & uploads

Choose when files upload. Keep transport in JavaScript and file references in form values.

Configure the field

{
  "type": "file",
  "key": "attachments",
  "multiple": true,
  "maxFiles": 3,
  "maxSize": 2097152,
  "accept": [
    ".pdf",
    ".txt"
  ],
  "view": {
    "label": "Attachments"
  },
  "upload": {
    "api": "backend",
    "endpoint": "files",
    "timing": "submit"
  }
}

Every file field needs upload configuration. Timing is submit or selection. Limits are checked before upload; maxSize is bytes. The browser sends multipart form data. The server must validate uploads independently.

Server response

{
  "id": "stored-file-id",
  "url": "https://files.example.com/stored-file-id"
}

The response must contain a nonempty string ID. An optional upload.resultPath extracts an envelope before checking the response. Uploaded references retain name, size, mediaType, and uploaded status. Submit waits for required uploads to finish; failures stay visible and retryable.

Drafts and reopening

Save uploaded references with your draft data. Browser File objects and unuploaded bytes are kept only in the current session and cannot be restored from ordinary JSON. A reopened draft with pending local files needs reselection or host-managed persistent storage. Upload on selection is useful when drafts need reloadable references before submission.

Try upload on selection → · Try upload on submit →