Uploads

<LightDarkImage srcLight="https://payloadcms.com/images/docs/uploads-overview.jpg" srcDark="https://payloadcms.com/images/docs/uploads-overview.jpg" alt="Shows an Upload enabled collection in the Payload Admin Panel" caption="Admin Panel screenshot depicting a Media Collection with Upload enabled" />

Here are some common use cases of Uploads:

• Creating a "Media Library" that contains images for use throughout your site or app
• Building a Gated Content library where users need to sign up to gain access to downloadable assets like ebook PDFs, whitepapers, etc.
• Storing publicly available, downloadable assets like software, ZIP files, MP4s, etc.

By simply enabling Upload functionality on a Collection, Payload will automatically transform your Collection into a robust file management / storage solution. The following modifications will be made:

1. filename, mimeType, and filesize fields will be automatically added to your Collection. Optionally, if you pass imageSizes to your Collection's Upload config, a sizes array will also be added containing auto-resized image sizes and filenames.
2. The Admin Panel will modify its built-in List component to show a thumbnail for each upload within the List View
3. The Admin Panel will modify its Edit view(s) to add a new set of corresponding Upload UI which will allow for file upload
4. The create, update, and delete Collection operations will be modified to support file upload, re-upload, and deletion

Enabling Uploads

Every Payload Collection can opt-in to supporting Uploads by specifying the upload property on the Collection's config to either true or to an object containing upload options.

A common pattern is to create a "media" collection and enable upload on that collection.

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    staticDir: 'media',
    imageSizes: [
      {
        name: 'thumbnail',
        width: 400,
        height: 300,
        position: 'centre',
      },
      {
        name: 'card',
        width: 768,
        height: 1024,
        position: 'centre',
      },
      {
        name: 'tablet',
        width: 1024,
        // By specifying `undefined` or leaving a height undefined,
        // the image will be sized to a certain width,
        // but it will retain its original aspect ratio
        // and calculate a height automatically.
        height: undefined,
        position: 'centre',
      },
    ],
    adminThumbnail: 'thumbnail',
    mimeTypes: ['image/*'],
  },
  fields: [
    {
      name: 'alt',
      type: 'text',
    },
  ],
}

Collection Upload Options

An asterisk denotes that an option is required.

Payload-wide Upload Options

Upload options are specifiable on a Collection by Collection basis, you can also control app wide options by passing your base Payload Config an upload property containing an object supportive of all Busboy configuration options.

Click here for more documentation about what you can control with Busboy.

A common example of what you might want to customize within Payload-wide Upload options would be to increase the allowed fileSize of uploads sent to Payload:

import { buildConfig } from 'payload'

export default buildConfig({
  collections: [
    {
      slug: 'media',
      fields: [
        {
          name: 'alt',
          type: 'text',
        },
      ],
      upload: true,
    },
  ],
  upload: {
    limits: {
      fileSize: 5000000, // 5MB, written in bytes
    },
  },
})

Custom filename via hooks

You can customize the filename before it's uploaded to the server by using a beforeOperation hook.

beforeOperation: [
  ({ req, operation }) => {
    if ((operation === 'create' || operation === 'update') && req.file) {
      req.file.name = 'test.jpg'
    }
  },
],

The req.file object will have additional information about the file, such as mimeType and extension, and you also have full access to the file data itself. The filename from here will also be threaded to image sizes if they're enabled.

Image Sizes

If you specify an array of imageSizes to your upload config, Payload will automatically crop and resize your uploads to fit each of the sizes specified by your config.

The Admin Panel will also automatically display all available files, including width, height, and file size, for each of your uploaded files.

Behind the scenes, Payload relies on sharp to perform its image resizing. You can specify additional options for sharp to use while resizing your images.

Note that for image resizing to work, sharp must be specified in your Payload Config. This is configured by default if you created your Payload project with create-payload-app. See sharp in Config Options.

Admin List View Options

Each image size also supports admin options to control whether it appears in the Admin Panel list view.

{
  name: 'thumbnail',
  width: 400,
  height: 300,
  admin: {
    disableGroupBy: true, // hide from list view groupBy options
    disableListColumn: true, // hide from list view columns
    disableListFilter: true, // hide from list view filters
  },
}

This is useful for hiding large or rarely used image sizes from the list view UI while still keeping them available in the API.

Accessing the resized images in hooks

All auto-resized images are exposed to be reused in hooks and similar via an object that is bound to req.payloadUploadSizes.

The object will have keys for each size generated, and each key will be set equal to a buffer containing the file data.

Handling Image Enlargement

When an uploaded image is smaller than the defined image size, we have 3 options:

withoutEnlargement: undefined | false | true

1. undefined [default]: uploading images with smaller width AND height than the image size will return null
2. false: always enlarge images to the image size
3. true: if the image is smaller than the image size, return the original image

By default, the image size will return NULL when the uploaded image is smaller than the defined image size. Use the withoutEnlargement prop to change this.

Custom file name per size

Each image size supports a generateImageName function that can be used to generate a custom file name for the resized image. This function receives the original file name, the resize name, the extension, height and width as arguments.

{
  name: 'thumbnail',
  width: 400,
  height: 300,
  generateImageName: ({ height, sizeName, extension, width }) => {
    return `custom-${sizeName}-${height}-${width}.${extension}`
  },
}

Crop and Focal Point Selector

This feature is only available for image file types.

Setting crop: false and focalPoint: false in your Upload config will be disable the respective selector in the Admin Panel.

Image cropping occurs before any resizing, the resized images will therefore be generated from the cropped image (not the original image).

If no resizing options are specified (imageSizes or resizeOptions), the focal point selector will not be displayed.

Disabling Local Upload Storage

If you are using a plugin to send your files off to a third-party file storage host or CDN, like Amazon S3 or similar, you may not want to store your files locally at all. You can prevent Payload from writing files to disk by specifying disableLocalStorage: true on your collection's upload config.

This is a fairly advanced feature. If you do disable local file storage, by default, your admin panel's thumbnails will be broken as you will not have stored a file. It will be totally up to you to use either a plugin or your own hooks to store your files in a permanent manner, as well as provide your own admin thumbnail using upload.adminThumbnail.

Admin Thumbnails

You can specify how Payload retrieves admin thumbnails for your upload-enabled Collections with one of the following:

1. adminThumbnail as a string, equal to one of your provided image size names.

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    // highlight-start
    adminThumbnail: 'small',
    // highlight-end
    imageSizes: [
      {
        name: 'small',
        fit: 'cover',
        height: 300,
        width: 900,
      },
      {
        name: 'large',
        fit: 'cover',
        height: 600,
        width: 1800,
      },
    ],
  },
}

2. adminThumbnail as a function that takes the document's data and sends back a full URL to load the thumbnail.

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    // highlight-start
    adminThumbnail: ({ doc }) =>
      `https://google.com/custom-path-to-file/${doc.filename}`,
    // highlight-end
  },
}

Customizing the Upload UI

You can completely customize the upload interface in the Admin Panel by swapping in your own React components. This allows you to modify how files are uploaded, add custom fields, integrate custom actions, or enhance the upload experience.

Upload Component Configuration

To customize the upload UI for an upload-enabled collection, use the admin.components.edit.Upload property in your Collection Config:

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: true,
  admin: {
    components: {
      edit: {
        Upload: '/components/CustomUpload#CustomUploadServer',
      },
    },
  },
  fields: [
    {
      name: 'alt',
      type: 'text',
    },
  ],
}

Building Custom Upload Components

Custom upload components must integrate with Payload's form system to work correctly. The recommended approach is to use Payload's built-in <Upload> component from @payloadcms/ui and wrap it with additional functionality.

Basic Example

Here's a minimal example showing how to create a custom upload component:

Server Component (/components/CustomUpload.tsx):

import React from 'react'
import type {
  PayloadServerReactComponent,
  SanitizedCollectionConfig,
} from 'payload'
import { CustomUploadClient } from './CustomUpload.client'

export const CustomUploadServer: PayloadServerReactComponent<
  SanitizedCollectionConfig['admin']['components']['edit']['Upload']
> = (props) => {
  return (
    <div>
      <h2>Custom Upload Interface</h2>
      <CustomUploadClient {...props} />
    </div>
  )
}

Client Component (/components/CustomUpload.client.tsx):

'use client'
import React from 'react'
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}
    />
  )
}

Advanced Example with Custom Actions

You can add custom actions, drawers, and fields to enhance the upload experience:

'use client'
import React from 'react'
import {
  Drawer,
  DrawerToggler,
  TextField,
  Upload,
  useDocumentInfo,
} from '@payloadcms/ui'

const customDrawerSlug = 'custom-upload-drawer'

const CustomDrawer = () => {
  return (
    <Drawer slug={customDrawerSlug}>
      <h2>Custom Upload Options</h2>
      <TextField
        field={{
          name: 'customField',
          label: 'Custom Field',
          type: 'text',
        }}
        path="customField"
      />
    </Drawer>
  )
}

const CustomDrawerToggler = () => {
  return (
    <DrawerToggler slug={customDrawerSlug}>
      <button type="button">Open Custom Options</button>
    </DrawerToggler>
  )
}

export const CustomUploadClient = () => {
  const { collectionSlug, docConfig, initialState } = useDocumentInfo()

  return (
    <div>
      <CustomDrawer />
      <Upload
        collectionSlug={collectionSlug}
        customActions={[<CustomDrawerToggler key="custom-drawer" />]}
        initialState={initialState}
        uploadConfig={'upload' in docConfig ? docConfig.upload : undefined}
      />
    </div>
  )
}

Available Hooks and Components

When building custom upload components, you have access to several useful hooks and components from @payloadcms/ui:

Custom Upload Fields vs. Custom Upload Collections

It's important to understand the difference between these two customization approaches:

Example of Upload Field Customization:

import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    {
      name: 'featuredImage',
      type: 'upload',
      relationTo: 'media',
      admin: {
        components: {
          Field: '/components/CustomUploadField',
        },
      },
    },
  ],
}

For more details on customizing fields, see Field Components.

Component Export Syntax

Custom components are referenced using file paths. Both default exports and named exports are supported:

// Named export with hash syntax
Upload: '/components/CustomUpload#CustomUploadServer'

// Default export (no hash needed)
Upload: '/components/CustomUpload'

// Alternative: using exportName property
Upload: {
  path: '/components/CustomUpload',
  exportName: 'CustomUploadServer',
}

For more details on component paths, see Custom Components.

Restricted File Types

Possibly problematic file types are automatically restricted from being uploaded to your application. If your Collection has defined mimeTypes or has set allowRestrictedFileTypes to true, restricted file verification will be skipped.

Restricted file types and extensions:

MimeTypes

Specifying the mimeTypes property can restrict what files are allowed from the user's file picker. This accepts an array of strings, which can be any valid mimetype or mimetype wildcards

Some example values are: image/*, audio/*, video/*, image/png, application/pdf

Example mimeTypes usage:

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    mimeTypes: ['image/*', 'application/pdf'], // highlight-line
  },
}

Uploading Files

Uploading files is currently only possible through the REST and Local APIs due to how GraphQL works. It's difficult and fairly nonsensical to support uploading files through GraphQL.

To upload a file, use your collection's create endpoint. Send it all the data that your Collection requires, as well as a file key containing the file that you'd like to upload.

Send your request as a multipart/form-data request, using FormData if possible.

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,
  /**
   * Do not manually add the Content-Type Header
   * the browser will handle this.
   *
   * headers: {
   *  'Content-Type': 'multipart/form-data'
   * }
   */
})

Uploading Files stored locally

If you want to upload a file stored on your machine directly using the payload.create method, for example, during a seed script, you can use the filePath property to specify the local path of the file.

const localFilePath = path.resolve(__dirname, filename)

await payload.create({
  collection: 'media',
  data: {
    alt,
  },
  filePath: localFilePath,
})

The data property should still include all the required fields of your media collection.

Remember that all custom hooks attached to the media collection will still trigger. Ensure that files match the specified mimeTypes or sizes defined in the collection's formatOptions or custom hooks.

Uploading Files from Remote URLs

The pasteURL option allows users to fetch files from remote URLs by pasting them into an Upload field. This option is enabled by default and can be configured to either allow unrestricted client-side fetching or restrict server-side fetching to specific trusted domains.

By default, Payload uses client-side fetching, where the browser downloads the file directly from the provided URL. However, client-side fetching will fail if the URL’s server has CORS restrictions, making it suitable only for internal URLs or public URLs without CORS blocks.

To fetch files from restricted URLs that would otherwise be blocked by CORS, use server-side fetching by configuring the pasteURL option with an allowList of trusted domains. This method ensures that Payload downloads the file on the server and streams it to the browser. However, for security reasons, only URLs that match the specified allowList will be allowed.

Configuration Example

Here’s how to configure the pasteURL option to control remote URL fetching:

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    pasteURL: {
      allowList: [
        {
          hostname: 'payloadcms.com', // required
          pathname: '',
          port: '',
          protocol: 'https',
          search: '',
        },
        {
          hostname: 'example.com',
          pathname: '/images/*',
        },
      ],
    },
  },
}

You can also adjust server-side fetching at the upload level as well, this does not effect the CORS policy like the pasteURL option does, but it allows you to skip the safe fetch check for specific URLs.

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    skipSafeFetch: [
      {
        hostname: 'example.com',
        pathname: '/images/*',
      },
    ],
  },
}

Accepted Values for pasteURL

AllowItem Properties

An asterisk denotes that an option is required.

Access Control

All files that are uploaded to each Collection automatically support the read Access Control function from the Collection itself. You can use this to control who should be allowed to see your uploads, and who should not.

Modifying response headers

You can modify the response headers for files by specifying the modifyResponseHeaders option in your upload config. This option accepts an object with existing headers and allows you to manipulate the response headers for media files.

Modifying existing headers

With this method you can directly interface with the Headers object and modify the existing headers to append or remove headers.

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    modifyResponseHeaders: ({ headers }) => {
      headers.set('X-Frame-Options', 'DENY') // You can directly set headers without returning
    },
  },
}

Return new headers

You can also return a new Headers object with the modified headers. This is useful if you want to set new headers or remove existing ones.

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    modifyResponseHeaders: ({ headers }) => {
      const newHeaders = new Headers(headers) // Copy existing headers
      newHeaders.set('X-Frame-Options', 'DENY') // Set new header

      return newHeaders
    },
  },
}