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:
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.List
component to show a thumbnail for each upload within the List ViewEdit
view(s) to add a new set of corresponding Upload UI which will allow for file uploadcreate
, update
, and delete
Collection operations will be modified to support file upload, re-upload, and deletionEvery 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.
An asterisk denotes that an option is required.
Option | Description |
---|---|
adminThumbnail | Set the way that the Admin Panel will display thumbnails for this Collection. More |
bulkUpload | Allow users to upload in bulk from the list view, default is true |
crop | Set to false to disable the cropping tool in the Admin Panel. Crop is enabled by default. More |
disableLocalStorage | Completely disable uploading files to disk locally. More |
displayPreview | Enable displaying preview of the uploaded file in Upload fields related to this Collection. Can be locally overridden by displayPreview option in Upload field. More. |
externalFileHeaderFilter | Accepts existing headers and returns the headers after filtering or modifying. |
filesRequiredOnCreate | Mandate file data on creation, default is true. |
filenameCompoundIndex | Field slugs to use for a compount index instead of the default filename index. |
focalPoint | Set to false to disable the focal point selection tool in the Admin Panel. The focal point selector is only available when imageSizes or resizeOptions are defined. More |
formatOptions | An object with format and options that are used with the Sharp image library to format the upload file. More |
handlers | Array of Request handlers to execute when fetching a file, if a handler returns a Response it will be sent to the client. Otherwise Payload will retrieve and send back the file. |
imageSizes | If specified, image uploads will be automatically resized in accordance to these image sizes. More |
mimeTypes | Restrict mimeTypes in the file picker. Array of valid mimetypes or mimetype wildcards More |
resizeOptions | An object passed to the the Sharp image library to resize the uploaded file. More |
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. Defaults to your collection slug |
trimOptions | An object passed to the the Sharp image library to trim the uploaded file. More |
withMetadata | If specified, appends metadata to the output image file. Accepts a boolean or a function that receives metadata and req , returning a boolean. |
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.
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 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 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.
When an uploaded image is smaller than the defined image size, we have 3 options:
withoutEnlargement: undefined | false | true
undefined
[default]: uploading images with smaller width AND height than the image size will return nullfalse
: always enlarge images to the image sizetrue
: if the image is smaller than the image size, return the original imageEach 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.
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.
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 with one of the following:
adminThumbnail
as a string, equal to one of your provided image size names.adminThumbnail
as a function that takes the document's data and sends back a full URL to load the thumbnail.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:
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.
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.