From 83319be752f715b869ea9593cb4d4bbc90a907cb Mon Sep 17 00:00:00 2001 From: Patrik Date: Mon, 7 Apr 2025 14:06:03 -0400 Subject: [PATCH] docs: clarify file upload example with `_payload` & field explanation (#12025) ### What? This PR updates the `Uploading Files` section in the `Uploads` docs to: - Use `_payload` in the file upload example, which is required for non-file fields to be parsed correctly by Payload. - Add a clear comment explaining that the fields inside `_payload` should match the schema of the upload-enabled collection. ### Why? These changes aim to reduce confusion when uploading files via the REST API. Fixes #11681 --- docs/admin/locked-documents.mdx | 3 +-- docs/upload/overview.mdx | 16 ++++++++++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/admin/locked-documents.mdx b/docs/admin/locked-documents.mdx index d37f3fda26..ad423d0aa2 100644 --- a/docs/admin/locked-documents.mdx +++ b/docs/admin/locked-documents.mdx @@ -21,10 +21,9 @@ When a user starts editing a document, Payload locks it for that user. If anothe The lock will automatically expire after a set period of inactivity, configurable using the `duration` property in the `lockDocuments` configuration, after which others can resume editing. - {' '} **Note:** If your application does not require document locking, you can disable this feature for any collection or global by setting the - `lockDocuments` property to `false`.{' '} + `lockDocuments` property to `false`. ### Config Options diff --git a/docs/upload/overview.mdx b/docs/upload/overview.mdx index 6e86b41e7a..fe3e3de708 100644 --- a/docs/upload/overview.mdx +++ b/docs/upload/overview.mdx @@ -334,12 +334,28 @@ To upload a file, use your collection's [`create`](/docs/rest-api/overview#colle Send your request as a `multipart/form-data` request, using [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) if possible. + + **Note:** To include any additional fields (like `title`, `alt`, etc.), append + a `_payload` field containing a JSON-stringified object of the required + values. These values must match the schema of your upload-enabled collection. + + ```ts const fileInput = document.querySelector('#your-file-input') const formData = new FormData() formData.append('file', fileInput.files[0]) +// Replace with the fields defined in your upload-enabled collection. +// The example below includes an optional field like 'title'. +formData.append( + '_payload', + JSON.stringify({ + title: 'Example Title', + description: 'An optional description for the file', + }), +) + fetch('api/:upload-slug', { method: 'POST', body: formData,