Upload Field
Admin panel screenshot of an Upload field
Example uses:
- To provide a
Pagewith a featured image - To allow for a
Productto deliver a downloadable asset like PDF or MP3 - To give a layout building block the ability to feature a background image
Config
| Option | Description |
|---|---|
name * | To be used as the property name when stored and retrieved from the database. More |
*relationTo * | Provide a single collection slug to allow this field to accept a relation to. Note: the related collection must be configured to support Uploads. |
filterOptions | A query to filter which options appear in the UI and validate against. More. |
maxDepth | Sets a number limit on iterations of related documents to populate when queried. Depth |
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. |
validate | Provide a custom validation function that will be executed on both the Admin panel and the backend. More |
index | Build an index 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, include its data in the user JWT. |
hooks | Provide field-based hooks to control logic for this field. More |
access | Provide field-based access control to denote what users can see and do with this field's data. More |
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 |
displayPreview | Enable displaying preview of the uploaded file. Overrides related Collection's displayPreview option. More. |
localized | Enable localization for this field. Requires localization to be enabled in the Base config. |
required | Require this field to have a value. |
admin | Admin-specific configuration. See the default field admin config for more details. |
custom | Extension point for adding custom data (e.g. for plugins) |
* An asterisk denotes that a property is required.
Example
collections/ExampleCollection.ts
1
import { CollectionConfig } from 'payload/types'
2
3
export const ExampleCollection: CollectionConfig = {
4
slug: 'example-collection',
5
fields: [
6
{
7
name: 'backgroundImage', // required
8
type: 'upload', // required
9
relationTo: 'media', // required
10
required: true,
11
},
12
],
13
}
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:
| Property | Description |
|---|---|
relationTo | The relationTo to filter against (as defined on the field) |
data | An object of the full collection or global document currently being edited |
siblingData | An object of the document data limited to fields within the same parent to the field |
id | The value of the collection id, will be undefined on create request |
user | The currently authenticated user object |
Example:
1
const uploadField = {
2
name: 'image',
3
type: 'upload',
4
relationTo: 'media',
5
filterOptions: {
6
mimeType: { contains: 'image' },
7
},
8
}
You can learn more about writing queries here.
Next