Upload

The Upload component is the file interface used by upload-enabled Collection Edit Views. It coordinates file selection, form state, existing file details, image adjustments, preview sizes, and upload status.

Import

1import { Upload, useDocumentInfo } from '@payloadcms/ui'

Edit View usage

Render Upload from a custom admin.components.edit.Upload component. That location supplies the form and document contexts the component requires.

1'use client'
2
3import { Upload, useDocumentInfo } from '@payloadcms/ui'
4
5export function CustomUpload() {
6  const { collectionSlug, docConfig, initialState } = useDocumentInfo()
7
8  const uploadConfig =
9    docConfig && 'upload' in docConfig ? docConfig.upload : undefined
10
11  // `collectionSlug` and `uploadConfig` are required, and `docConfig` is
12  // undefined until the document's config has resolved
13  if (!collectionSlug || !uploadConfig) {
14    return null
15  }
16
17  return (
18    <Upload
19      collectionSlug={collectionSlug}
20      initialState={initialState}
21      uploadConfig={uploadConfig}
22    />
23  )
24}

Configure the component on an upload-enabled Collection:

1import type { CollectionConfig } from 'payload'
2
3export const Media: CollectionConfig = {
4  slug: 'media',
5  upload: true,
6  admin: {
7    components: {
8      edit: {
9        Upload: '/components/CustomUpload',
10      },
11    },
12  },
13}

File selection

The empty Upload state composes Payload's Dropzone for drag, drop, paste, and file selection behavior.

or drag and drop files here

Loading component example…

Use Dropzone directly when you only need file intake. Use Upload when the file must participate in an upload-enabled Collection's form and persistence workflow.

Custom actions

Pass customActions to place additional controls beside Payload's upload actions.

1<Upload
2  collectionSlug={collectionSlug}
3  customActions={[<MyUploadAction key="my-action" />]}
4  initialState={initialState}
5  uploadConfig={uploadConfig}
6/>

Common props

These are the props most commonly used with this component. See its exported types in @payloadcms/ui for the complete list.

Prop	Type	Default	Description
`collectionSlug` *	`string`	—	Identifies the upload-enabled Collection.
`uploadConfig` *	`SanitizedCollectionConfig['upload']`	—	Supplies the Collection's sanitized upload options.
`initialState`	`FormState`	—	Supplies an initial file from the surrounding Edit View.
`onChange`	`(file?: File) => void`	—	Runs when the selected file changes.
`customActions`	`ReactNode[]`	—	Adds controls beside the built-in upload actions.
`UploadControls`	`ReactNode`	—	Supplies custom controls for the upload workflow.

* An asterisk denotes that a prop is required.

Provider requirements

Upload is not a standalone website file input. It consumes Payload's Config, DocumentInfo, Form, Translation, Modal, UploadControls, and UploadEdits contexts. Use it in the upload Edit View override shown above rather than constructing those providers manually.

For the complete customization path, see Customizing the Upload UI.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.