Upload Field

The Upload Field allows for the selection of a Document from a Collection supporting Uploads, and formats the selection as a thumbnail in the Admin Panel.

Upload fields are useful for a variety of use cases, such as:

• To provide a Page with a featured image
• To allow for a Product to deliver a downloadable asset like PDF or MP3
• To give a layout building block the ability to feature a background image

<LightDarkImage srcLight="https://payloadcms.com/images/docs/fields/upload.png" srcDark="https://payloadcms.com/images/docs/fields/upload-dark.png" alt="Shows an upload field in the Payload Admin Panel" caption="Admin Panel screenshot of an Upload field" />

To create an Upload Field, set the type to upload in your Field Config:

import type { Field } from 'payload'

export const MyUploadField: Field = {
  // ...
  // highlight-start
  type: 'upload',
  relationTo: 'media',
  // highlight-end
}

Config Options

* An asterisk denotes that a property is required.

Example

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'backgroundImage', // required
      type: 'upload', // required
      relationTo: 'media', // required
      required: true,
    },
  ],
}

Filtering upload options

Options can be dynamically limited by supplying a query constraint, which will be used both for validating input and filtering available uploads in the UI.

The filterOptions property can either be a Where query, or a function returning true to not filter, false to prevent all, or a Where query. When using a function, it will be called with an argument object with the following properties:

Example#filter-options-example

const uploadField = {
  name: 'image',
  type: 'upload',
  relationTo: 'media',
  filterOptions: {
    mimeType: { contains: 'image' },
  },
}

You can learn more about writing queries here.

When an upload field has both filterOptions and a custom validate function, the api will not validate filterOptions unless you call the default upload field validation function imported from payload/shared in your validate function.

Bi-directional relationships

The upload field on its own is used to reference documents in an upload collection. This can be considered a "one-way" relationship. If you wish to allow an editor to visit the upload document and see where it is being used, you may use the join field in the upload enabled collection. Read more about bi-directional relationships using the Join field

Polymorphic Uploads

Upload fields can reference multiple upload collections by providing an array of collection slugs to the relationTo property.

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'media',
      type: 'upload',
      relationTo: ['images', 'documents', 'videos'], // references multiple upload collections
    },
  ],
}

This can be combined with the hasMany property to allow multiple uploads from multiple collections.

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'media',
      type: 'upload',
      relationTo: ['images', 'documents', 'videos'], // references multiple upload collections
      hasMany: true, // allows multiple uploads
    },
  ],
}