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:
Page
with a featured imageProduct
to deliver a downloadable asset like PDF or MP3To create an Upload Field, set the type
to upload
in your Field 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 Hooks to control logic for this field. More details. |
access | Provide Field Access Control to denote what users can see and do with this field's data. More details. |
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. Admin Options. |
custom | Extension point for adding custom data (e.g. for plugins) |
typescriptSchema | Override field type generation with providing a JSON schema |
* An asterisk denotes that a property is required.
collections/ExampleCollection.ts
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 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 |
You can learn more about writing queries here.