Media Upload

File upload (`media`) with edit vs preview modes — MIME and extension rules, multi-file caps, and optional `previewMedia` for display-only assets.

Overview

The media field collects files or presents a builder-authored asset, depending on mediaMode. In edit mode, respondents upload within the constraints you set; in preview mode, they only view a file you attached in the form definition.

Restrict types with acceptedTypes and/or allowedExtensions (when set, extensions take precedence for narrowing), and use blockedExtensions to reject risky archives or executables outright.

Patterns

Edit (upload) — mediaMode omitted or "edit". One file by default; set multiple and maxFiles for batches.
Preview (display-only) — mediaMode "preview" with previewMedia { url, name, size, type }. Respondents see the asset (image inline, PDF/other as a card link) but do not upload a replacement through this field.

Tip: Sizes are in bytes maxSize per file and optional maxTotalSize for the combined upload when multiple is true.

Properties

Note: Builder exports include an id (UUID) per field; submission payloads use those ids as keys.

Property	Type	Default	Description
id	string	—	Unique field identifier.
type	string	"media"	Discriminator.
label	string	—	Human-readable label shown above the field or step heading.
required	boolean	false	When true, the form cannot submit without a value.
isHidden	boolean	false	Hides the field from respondents (may still store defaults).
isDisabled	boolean	false	Renders the field read-only.
instruction	string	undefined	Help text shown below the label (not the same as placeholder).
mediaMode	"edit" \| "preview"	"edit"	Upload UX vs static display using previewMedia.
previewMedia	object	undefined	Preview mode: { url, name, size, type } shown to respondents.
multiple	boolean	false	Allow more than one file in edit mode.
maxFiles	number	undefined	Max files when multiple is true (enforce explicitly in form design).
maxSize	number	undefined	Max size per file in bytes (e.g. 10485760 for 10 MB).
maxTotalSize	number	undefined	Optional combined cap for all files in bytes.
acceptedTypes	string[]	undefined	MIME accept list (e.g. image/*, application/pdf).
fileTypes	('photo' \| 'audio' \| 'video' \| 'barcode' \| 'file' \| 'xml')[]	undefined	One or more category tags for upload behaviour and UX hints.
allowedExtensions	string[]	undefined	When set, drives emphasis over acceptedTypes (e.g. .pdf, .png).
blockedExtensions	string[]	undefined	Always rejected (e.g. .exe, .zip) for safer uploads.
instruction	string	undefined	Help text below the label.
reporting	object	undefined	Admin tables: includeInTable, labelOverride, sortable, filterable.
integrationKey	string	undefined	Stable alias for exports or external systems.

JSON examples

Edit mode — photo upload (export shape)

{
  "name": "Intake",
  "weightage": 0,
  "fields": [
    {
      "id": "1633df1b-d24c-40c0-b979-f85525adf507",
      "type": "media",
      "label": "Profile photo",
      "required": true,
      "isHidden": false,
      "placeholder": "Upload a clear headshot...",
      "multiple": false,
      "maxFiles": 1,
      "maxSize": 5242880,
      "fileTypes": ["photo"],
      "acceptedTypes": ["image/*"],
      "allowedExtensions": [".jpg", ".jpeg", ".png", ".webp"],
      "blockedExtensions": [".exe", ".zip", ".rar"]
    }
  ]
}

Preview mode — handout PDF configured in builder

{
  "name": "Intake",
  "weightage": 0,
  "fields": [
    {
      "id": "1633df1b-d24c-440c-b979-f85525adf507",
      "type": "media",
      "label": "Participant handbook",
      "required": false,
      "isHidden": false,
      "mediaMode": "preview",
      "previewMedia": {
        "url": "https://cdn.example.com/forms/handbook-2026.pdf",
        "name": "handbook-2026.pdf",
        "size": 892144,
        "type": "application/pdf"
      }
    }
  ]
}

Stored value

In edit mode, typically one object { name, size, type, url?, id? } or, when multiple is true, an array of those objects (up to maxFiles). Exact keys match your uploader and API after processing.

In preview mode, respondents do not upload through this field; the visible file is defined on the field as previewMedia. Submission payloads usually omit a user file for this field id.

Use cases

Résumés, transcripts, or signed PDFs with strict extension allow-lists
Evidence photos for inspections, warranty claims, or field reports
Preview mode to show consent PDFs, maps, or instructions beside attestations
Design deliverables or portfolios tied to structured metadata fields

PreviousRich Text

NextMap / Geolocation