vault backup: 2026-05-15 16:53:02

wiki/payloadcms/upload.md

@@ -1,8 +1,11 @@
 ---
-tags: [payloadcms, tech-patterns]
+title: "PayloadCMS — Upload & Media"
+aliases: [payload-upload, payload-media, payload-file-upload]
+tags: [payloadcms, tech-patterns, upload, media]
 topic: payloadcms
 sources: [upload__overview.md, upload__storage-adapters.md]
 created: 2026-05-15
+updated: 2026-05-15
 ---
 
 # PayloadCMS — Upload & Media
@@ -71,6 +74,13 @@ export default buildConfig({
 | `withMetadata` | Append EXIF metadata to output image |
 | `modifyResponseHeaders` | Manipulate HTTP response headers for served files |
 | `allowRestrictedFileTypes` | `true` to bypass blocked executable/script extension list |
+| `hideFileInputOnCreate` | `true` to hide file input during document creation (for programmatic file generation) |
+| `hideRemoveFile` | `true` to hide the remove-file button in the edit view |
+| `constructorOptions` | Object passed to Sharp constructor (applied to every upload file) |
+| `cacheTags` | `false` to disable cache tags set in UI for the admin thumbnail (for CDNs that block cache queries) |
+| `externalFileHeaderFilter` | Filter/modify headers when fetching external files; must strip `payload-*` cookies manually if provided |
+| `filenameCompoundIndex` | Field slugs for a compound index instead of the default filename index |
+| `skipSafeFetch` | `allowList` array or `true` — skip safe-fetch SSRF check for specific/all external URLs |
 
 ### Image sizes — `withoutEnlargement`
 
@@ -90,7 +100,23 @@ beforeOperation: [
 ],
 ```
 
-Custom per-size filename:
+### Image size admin list view options
+
+Hide specific sizes from the list view UI while keeping them available in the API:
+
+```ts
+{
+  name: 'thumbnail',
+  width: 400, height: 300,
+  admin: {
+    disableGroupBy: true,    // hide from groupBy options
+    disableListColumn: true, // hide from column picker
+    disableListFilter: true, // hide from filter options
+  },
+}
+```
+
+### Custom per-size filename
 
 ```ts
 {
@@ -144,6 +170,70 @@ upload: {
 }
 ```
 
+## Custom Upload UI
+
+You can replace the default upload interface with custom React components via `admin.components.edit.Upload`.
+
+> **Critical:** Never use a raw `<input type="file" />` — it won't connect to Payload's form state and causes `400 Bad Request`. Always use Payload's `<Upload>` component from `@payloadcms/ui`.
+
+### Minimal example
+
+**Server Component** (`/components/CustomUpload.tsx`):
+```tsx
+import { CustomUploadClient } from './CustomUpload.client'
+export const CustomUploadServer = (props) => (
+  <div>
+    <h2>Custom Upload Interface</h2>
+    <CustomUploadClient {...props} />
+  </div>
+)
+```
+
+**Client Component** (`/components/CustomUpload.client.tsx`):
+```tsx
+'use client'
+import { Upload, useDocumentInfo } from '@payloadcms/ui'
+export const CustomUploadClient = () => {
+  const { collectionSlug, docConfig, initialState } = useDocumentInfo()
+  return (
+    <Upload
+      collectionSlug={collectionSlug}
+      initialState={initialState}
+      uploadConfig={'upload' in docConfig ? docConfig.upload : undefined}
+    />
+  )
+}
+```
+
+**Collection config:**
+```ts
+admin: {
+  components: {
+    edit: {
+      Upload: '/components/CustomUpload#CustomUploadServer',
+    },
+  },
+},
+```
+
+### Available hooks & components from `@payloadcms/ui`
+
+| Hook / Component | Description |
+|---|---|
+| `useDocumentInfo()` | Collection slug, doc config, initial state |
+| `useField()` | Access/manipulate form field state |
+| `useBulkUpload()` | Bulk upload context |
+| `<Upload>` | Main upload component (drag-drop, preview, `customActions` prop) |
+| `<Drawer>` / `<DrawerToggler>` | Modal drawer + trigger button |
+| `<TextField>` etc. | Form field components |
+
+### Upload Collection vs Upload Field customization
+
+| Approach | Config location | Use case |
+|---|---|---|
+| Upload Collection | `admin.components.edit.Upload` | Customize the media collection edit view |
+| Upload Field | `admin.components.Field` on an upload field | Customize the field that references uploads in other collections |
+
 ## Storage Adapters
 
 All adapters auto-set `disableLocalStorage: true` per collection.