Admin panel screenshot depicting a Media Collection with Upload enabled
Here are some common use cases of Uploads:
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:
filesizefields will be automatically added to your Collection. Optionally, if you pass
imageSizesto your Collection's Upload config, a
sizesarray will also be added containing auto-resized image sizes and filenames.
Listcomponent to show a thumbnail gallery of your Uploads instead of the default Table view
Editview(s) to add a new set of corresponding Upload UI which will allow for file upload
deleteCollection operations will be modified to support file upload, re-upload, and deletion
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
|The base URL path to use to access your uploads. Example: |
|The folder directory to use to store media in. Can be either an absolute path or relative to the directory that contains your config.|
|If specified, image uploads will be automatically resized in accordance to these image sizes. More|
|An object with |
|An object passed to the the Sharp image library to resize the uploaded file. More|
|Set the way that the Admin panel will display thumbnails for this Collection. More|
|Restrict mimeTypes in the file picker. Array of valid mimetypes or mimetype wildcards More|
|Completely disable uploading files to disk locally. More|
|Set options for |
|Array of Express request handlers to execute before the built-in Payload static middleware executes.|
An asterisk denotes that a property above is required.
Example Upload collection:
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:
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.
All auto-resized images are exposed to be re-used in hooks and similar via an object that is bound to
The object will have keys for each size generated, and each key will be set equal to a buffer containing the file data.
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.
You can specify how Payload retrieves admin thumbnails for your upload-enabled Collections. This property accepts two different configurations:
Example custom Admin thumbnail:
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:
Example mimeTypes usage:
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.
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.