Upload admin panel functionality 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 gallery of your Uploads instead of the default Table 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.

Collection Upload Options

staticURL *The base URL path to use to access you uploads. Example: /media
staticDir *The folder directory to use to store media in. Can be either an absolute path or relative to the directory that contains your config.
imageSizesIf specified, image uploads will be automatically resized in accordance to these image sizes. More
adminThumbnailWhich of your provided image sizes to use for the admin panel's thumbnail. Typically a size around 500x500px or so works well.

An asterisk denotes that a property above is required.

Example Upload collection:

const Media = {
slug: 'media',
upload: {
staticURL: '/media',
staticDir: 'media',
imageSizes: [
name: 'thumbnail',
width: 400,
height: 300,
crop: 'centre',
name: 'card',
width: 768,
height: 1024,
crop: 'centre',
adminThumbnail: 'thumbnail',

Payload-wide Upload Options

Payload relies on the express-fileupload package to manage file uploads in Express. In addition to the Upload options specifiable on a Collection by Collection basis, you can also control the express-fileupload options by passing your base Payload config an upload property containing an object supportive of all express-fileupload properties which use Busboy under the hood. Click here for more documentation about what you can control.

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/config';
export default buildConfig({
serverURL: 'http://localhost:3000',
collections: [
slug: 'media',
fields: [
name: 'alt',
type: 'text',
upload: true,
upload: {
limits: {
fileSize: 5000000, // 5MB, written in bytes

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 Payload Admin panel will also automatically display all available files, including width, height, and filesize, 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.

Uploading Files

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.

Here is a walkthrough detailing how to upload files as multipart/form-data using React.

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.


Hooks Overview