feat(plugin-form-builder): add support for multi part uploads (#15268)

Adds support for multi part uploads directly in the plugin, this makes
it so you don't need to upload documents separately and instead the form
submissions themselves can handle this part.

Before
```ts
// Step 1: upload the file
const uploadForm = new FormData()
uploadForm.append('file', imageFile)
const { doc: media } = await fetch('/api/media', {
  method: 'POST',
  body: uploadForm,
}).then(r => r.json())

// Step 2: submit the form with the pre-uploaded ID
await fetch('/api/form-submissions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    form: formId,
    submissionData: [
      { field: 'fullName', value: 'Alice' },
      { field: 'avatar', value: media.id }, // string ID only
    ],
  }),
})
```

After

```ts
const formData = new FormData()
formData.append('_payload', JSON.stringify({
  form: formId,
  submissionData: [{ field: 'fullName', value: 'Alice' }],
}))
formData.append('avatar', imageFile) // keyed by field name

await fetch('/api/form-submissions', {
  method: 'POST',
  body: formData,
})

```

Author: paulpopus

docs/plugins/form-builder.mdx

@@ -88,6 +88,9 @@ formBuilderPlugin({
     message: true,
     date: false,
     payment: false,
+    upload: {
+      uploadCollections: ['media', 'documents'], // Required when using upload
+    },
   },
 })
 ```
@@ -441,6 +444,180 @@ Each of the `priceConditions` are executed by the `getPaymentTotal` utility that
 | `valueType`        | string       | The type of value to use to determine the price. |
 | `value`            | string       | The value to use to determine the price.         |
 
+### Upload
+
+Add this field to your form to collect file uploads. Files are stored in a specified upload-enabled collection, and the file ID is stored as the submission value. This field is disabled by default and must be explicitly enabled.
+
+| Property           | Type      | Description                                                                                  |
+| ------------------ | --------- | -------------------------------------------------------------------------------------------- |
+| `name`             | string    | The name of the field.                                                                       |
+| `label`            | string    | The label of the field.                                                                      |
+| `uploadCollection` | string \* | The slug of the upload-enabled collection to store files in.                                 |
+| `mimeTypes`        | array     | An array of allowed MIME types (e.g., `image/*`, `application/pdf`). Empty allows all types. |
+| `maxFileSize`      | number    | Maximum file size in bytes. Leave empty for no limit.                                        |
+| `width`            | number    | The width of the field as a percentage (e.g., `50` for 50%).                                 |
+| `required`         | checkbox  | Whether or not the field is required when submitted.                                         |
+| `multiple`         | checkbox  | Whether to allow multiple file uploads.                                                      |
+
+#### Enabling Upload Fields
+
+To use upload fields, enable the `upload` field and provide `uploadCollections` at the top level of the plugin config:
+
+```ts
+// payload.config.ts
+formBuilderPlugin({
+  fields: {
+    upload: true,
+  },
+  uploadCollections: ['media', 'documents'], // Required — available upload collections
+})
+```
+
+#### Frontend Implementation
+
+The simplest way to handle upload fields is to submit files directly with the form as `multipart/form-data`. The form builder will automatically upload files to the appropriate collection and store the file IDs in the submission.
+
+```ts
+async function submitFormWithFiles(
+  formId: string,
+  fields: FormField[],
+  values: Record<string, any>,
+) {
+  const formData = new FormData()
+
+  // Build submission data for non-file fields
+  const submissionData = []
+
+  for (const field of fields) {
+    if (field.blockType === 'upload') {
+      // Files are appended to FormData separately using the field name
+      if (values[field.name]) {
+        formData.append(field.name, values[field.name])
+      }
+    } else if (values[field.name] !== undefined) {
+      submissionData.push({ field: field.name, value: values[field.name] })
+    }
+  }
+
+  // Add the form ID and non-file submission data as JSON
+  formData.append(
+    '_payload',
+    JSON.stringify({
+      form: formId,
+      submissionData,
+    }),
+  )
+
+  const response = await fetch('/api/form-submissions', {
+    method: 'POST',
+    body: formData,
+  })
+
+  return response.json()
+}
+```
+
+The server will:
+
+1. Validate MIME types and file sizes against the field configuration
+2. Upload files to the specified upload collection
+3. Store the created file IDs in the submission data
+
+#### Alternative: Pre-upload Files
+
+If you prefer more control over the upload process (e.g., for progress tracking or resumable uploads), you can upload files separately and submit their IDs:
+
+```ts
+// 1. Upload file to the upload collection
+async function uploadFile(file: File, collectionSlug: string) {
+  const formData = new FormData()
+  formData.append('file', file)
+
+  const response = await fetch(`/api/${collectionSlug}`, {
+    method: 'POST',
+    body: formData,
+  })
+
+  return response.json() // { doc: { id, filename, ... } }
+}
+
+// 2. Submit form with file ID
+async function submitFormWithFileIds(
+  formId: string,
+  fields: FormField[],
+  values: Record<string, any>,
+) {
+  const submissionData = []
+
+  for (const field of fields) {
+    if (field.blockType === 'upload' && values[field.name]) {
+      // Upload file first
+      const uploadResult = await uploadFile(
+        values[field.name],
+        field.uploadCollection,
+      )
+      submissionData.push({ field: field.name, value: uploadResult.doc.id })
+    } else {
+      submissionData.push({ field: field.name, value: values[field.name] })
+    }
+  }
+
+  await fetch('/api/form-submissions', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ form: formId, submissionData }),
+  })
+}
+```
+
+#### Using Presigned URLs for Large Files
+
+If your upload collection uses a storage adapter with `clientUploads` enabled (e.g., S3, Azure, GCS), you can upload files directly to cloud storage using presigned URLs for better performance with large files:
+
+```ts
+async function uploadWithPresignedUrl(
+  file: File,
+  collectionSlug: string,
+  serverHandlerPath: string = '/storage-s3-generate-signed-url',
+) {
+  // 1. Get presigned URL from Payload
+  const signedUrlResponse = await fetch(`/api${serverHandlerPath}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    credentials: 'include',
+    body: JSON.stringify({
+      collectionSlug,
+      filename: file.name,
+      filesize: file.size,
+      mimeType: file.type,
+    }),
+  })
+  const { url } = await signedUrlResponse.json()
+
+  // 2. Upload directly to cloud storage
+  // Note: the browser sets Content-Length automatically and forbids setting it manually.
+  await fetch(url, {
+    method: 'PUT',
+    body: file,
+    headers: {
+      'Content-Type': file.type,
+    },
+  })
+
+  // 3. Create document in Payload (file already in storage)
+  const docResponse = await fetch(`/api/${collectionSlug}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      filename: file.name,
+      mimeType: file.type,
+      filesize: file.size,
+    }),
+  })
+  return docResponse.json()
+}
+```
+
 ### Field Overrides
 
 You can provide your own custom fields by passing a new [Payload Block](https://payloadcms.com/docs/fields/blocks#block-configs) object into `fields`. You can override or extend any existing fields by first importing the `fields` from the plugin:
@@ -556,6 +733,8 @@ import type {
   FieldsConfig,
   BeforeEmail,
   HandlePayment,
+  UploadField,
+  UploadFieldMimeType,
   ...
 } from "@payloadcms/plugin-form-builder/types";
 ```

packages/payload/src/types/index.ts

@@ -22,6 +22,7 @@ import type {
   TypedLocale,
   TypedUser,
 } from '../index.js'
+import type { File } from '../uploads/types.js'
 import type { Operator } from './constants.js'
 export type { Payload } from '../index.js'
 
@@ -111,12 +112,9 @@ type PayloadRequestData = {
      * Context of the file when it was uploaded via client side.
      */
     clientUploadContext?: unknown
-    data: Buffer
-    mimetype: string
-    name: string
-    size: number
-    tempFilePath?: string
-  }
+  } & File
+  /** All files from multipart form data, keyed by field name */
+  files?: Record<string, File | File[]>
 }
 export interface PayloadRequest
   extends CustomPayloadRequestProperties,

packages/payload/src/utilities/addDataAndFileToRequest.ts

@@ -43,8 +43,14 @@ export const addDataAndFileToRequest: AddDataAndFileToRequest = async (req) => {
         throw new APIError(error.message)
       }
 
-      if (files?.file) {
-        req.file = files.file
+      // Set all files on req.files for access by hooks
+      if (files) {
+        req.files = files
+        // Backwards compatibility: set req.file for standard upload collections
+        // Guard: if multiple files share the field name "file", files.file is an array — skip
+        if (files.file && !Array.isArray(files.file)) {
+          req.file = files.file
+        }
       }
 
       if (fields?._payload && typeof fields._payload === 'string') {