# Upload Field Source: https://payloadcms.com/docs/fields/upload The Upload Field allows for the selection of a Document from a Collection supporting [Uploads](/docs/v3/upload/overview.md), 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 ![Shows an upload field in the Payload Admin Panel](https://payloadcms.com/images/docs/fields/upload.png) _Admin Panel screenshot of an Upload field_ To create an Upload Field, set the `type` to `upload` in your [Field Config](/docs/v3/fields/overview.md): ```ts import type { Field } from 'payload' export const MyUploadField: Field = { // ... // highlight-start type: 'upload', relationTo: 'media', // highlight-end } ``` > **Important:** To use the Upload Field, you must have a > [Collection](/docs/v3/configuration/collections.md) configured to allow > [Uploads](/docs/v3/upload/overview.md). ## Config Options | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`name`** \* | To be used as the property name when stored and retrieved from the database. [More details](/docs/v3/fields/overview.md#field-names). | | **`relationTo`** \* | Provide a single collection `slug` or an array of slugs to allow this field to accept a relation to. **Note: the related collections must be configured to support Uploads.** | | **`filterOptions`** | A query to filter which options appear in the UI and validate against. [More details](#filtering-upload-options). | | **`hasMany`** | Boolean which, if set to true, allows this field to have many relations instead of only one. | | **`minRows`** | A number for the fewest allowed items during validation when a value is present. Used with hasMany. | | **`maxRows`** | A number for the most allowed items during validation when a value is present. Used with hasMany. | | **`maxDepth`** | Sets a number limit on iterations of related documents to populate when queried. [Depth](/docs/v3/queries/depth.md) | | **`label`** | Text used as a field label in the Admin Panel or an object with keys for each language. | | **`unique`** | Enforce that each entry in the Collection has a unique value for this field. This creates a database-level unique index on the field's path. [More details](/docs/v3/database/indexes.md#unique-fields). | | **`validate`** | Provide a custom validation function that will be executed on both the Admin Panel and the backend. [More details](/docs/v3/fields/overview.md#validation). | | **`index`** | Build an [index](/docs/v3/database/indexes.md) for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often. | | **`saveToJWT`** | If this field is top-level and nested in a config supporting [Authentication](/docs/v3/authentication/overview.md), include its data in the user JWT. | | **`hooks`** | Provide Field Hooks to control logic for this field. [More details](/docs/v3/hooks/fields.md). | | **`access`** | Provide Field Access Control to denote what users can see and do with this field's data. [More details](/docs/v3/access-control/fields.md). | | **`hidden`** | Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin Panel. | | **`defaultValue`** | Provide data to be used for this field's default value. [More details](/docs/v3/fields/overview.md#default-values). | | **`displayPreview`** | Enable displaying preview of the uploaded file. Overrides related Collection's `displayPreview` option. [More details](/docs/v3/upload/overview.md#collection-upload-options). | | **`localized`** | Enable localization for this field. Requires [localization to be enabled](/docs/v3/configuration/localization.md) in the Base config. | | **`required`** | Require this field to have a value. | | **`admin`** | Admin-specific configuration. [Admin Options](/docs/v3/fields/overview.md#admin-options). | | **`custom`** | Extension point for adding custom data (e.g. for plugins) | | **`typescriptSchema`** | Override field type generation with providing a JSON schema | | **`virtual`** | Provide `true` to disable field in the database, or provide a string path to [link the field with a relationship](/docs/v3/fields/relationship.md#linking-virtual-fields-with-relationships). See [Virtual Fields](https://payloadcms.com/blog/learn-how-virtual-fields-can-help-solve-common-cms-challenges) | | **`graphQL`** | Custom graphQL configuration for the field. [More details](/docs/v3/graphql/overview.md#field-complexity) | _\* An asterisk denotes that a property is required._ ## Example ```ts 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](/docs/v3/queries/overview.md), 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: | Property | Description | | ------------- | ----------------------------------------------------------------------------------------------------- | | `relationTo` | The collection `slug` to filter against, limited to this field's `relationTo` property | | `data` | An object containing the full collection or global document currently being edited | | `siblingData` | An object containing document data that is scoped to only fields within the same parent of this field | | `id` | The `id` of the current document being edited. `id` is `undefined` during the `create` operation | | `user` | An object containing the currently authenticated user | | `req` | The Payload Request, which contains references to `payload`, `user`, `locale`, and more. | ### Example#filter-options-example ```ts const uploadField = { name: 'image', type: 'upload', relationTo: 'media', filterOptions: { mimeType: { contains: 'image' }, }, } ``` You can learn more about writing queries [here](/docs/v3/queries/overview.md). > **Note:** > > 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](/docs/v3/fields/join.md) ## Polymorphic Uploads Upload fields can reference multiple upload collections by providing an array of collection slugs to the `relationTo` property. ```ts 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. ```ts 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 }, ], } ```