Simplify your stack and build anything. Or everything.
Schedule a Demo
USE CASES
Headless CMSEnterprise App BuilderHeadless E-CommerceDigital Asset Management
FEATURES
Multi-TenancyWhite LabelLocalizationAccess ControlAuth
CASE STUDIES

See what others are building with Payload.

Browse Case Studies
Build tomorrow’s web with a modern solution you truly own.
PAYLOAD IS FOR
DevelopersMarketing teamsEnterprise companiesAgencies & Consultancies
COMPARE PAYLOAD
Payload vs WordPressPayload vs ContentfulPayload vs SanityPayload vs StrapiPayload vs Directus
AGENCY TESTIMONIAL

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

Become a PartnerFind a Partner
Code-based nature means you can build on top of it to power anything.
Resources
DocumentationExamplesTemplatesGitHubReleasesBlogGuides & Tutorials
Community
RoadmapDiscordCommunity Help
Resources for Developers

Get the resources you need to start building today

Guides & TutorialsExplore Docs
It’s time to take back your content infrastructure.
Schedule a Demo
Enterprise Features
SSOAI Auto-EmbeddingPublishing WorkflowsVisual EditorStatic A/B testingAI features
Customer Stories
MicrosoftASICSBlue OriginHello BelloTekton
Featured Customer Story

Microsoft chose Payload to tell the world about AI.

Read the case studyBrowse all
LoginGet Started

Upload Helpers

Payload's upload helpers support the file-management interface around an upload-enabled Collection. Use them when extending an upload workflow that already has a document, upload configuration, and the surrounding Admin context.

Import

1
import { EditUpload, FileDetails, PreviewSizes } from '@payloadcms/ui'

File details

FileDetails presents a file thumbnail, URL, dimensions, size, and MIME type. It can also display removal, image-adjustment, generated-size, and custom upload actions.

Loading component example…

The component renders a static summary by default. Pass the sortable row props when it represents one item in a multi-upload field.

Generated image sizes

PreviewSizes lets users compare the original upload with image sizes generated by the Collection's upload configuration.

Loading component example…

The available options come from uploadConfig.imageSizes and matching entries in doc.sizes. Selecting an option updates the main preview and metadata.

Image adjustments

EditUpload provides Payload's crop and focal-point controls. Use showCrop and showFocalPoint to expose the adjustments enabled by the upload Collection.

1
<EditUpload
2
fileName={doc.filename}
3
fileSrc={doc.url}
4
initialCrop={doc.crop}
5
initialFocalPoint={doc.focalPoint}
6
onSave={(uploadEdits) => updateUploadEdits(uploadEdits)}
7
showCrop
8
showFocalPoint
9
/>

onSave receives the crop, focal point, and resulting pixel dimensions. The component closes Payload's upload-edit modal after applying the changes.

Common props

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

FileDetails

Prop

Type

Default

Description

collectionSlug *

string

—

Identifies the upload-enabled Collection.

doc *

Data & { sizes?: FileSizes }

—

Supplies file metadata and generated sizes.

uploadConfig *

SanitizedCollectionConfig['upload']

—

Controls previews and available upload behavior.

enableAdjustments

boolean

false

Shows the image-adjustment action.

hasImageSizes

boolean

false

Shows the generated-size preview action.

hideRemoveFile

boolean

false

Hides the file-removal control.

customUploadActions

ReactNode[]

—

Adds project-specific upload actions.

PreviewSizes

Prop

Type

Default

Description

doc *

Data & { sizes?: Record<string, FileSize> }

—

Supplies original and generated image metadata.

uploadConfig *

SanitizedCollectionConfig['upload']

—

Defines the configured image-size order.

imageCacheTag

string

—

Appends a cache-busting tag to preview URLs.

EditUpload

Prop

Type

Default

Description

fileName *

string

—

Labels the image being edited.

fileSrc *

string

—

Supplies the image URL.

onSave

(edits: UploadEdits) => void

—

Receives the applied image adjustments.

showCrop

boolean

false

Enables crop controls.

showFocalPoint

boolean

false

Enables focal-point controls.

initialCrop

UploadEdits['crop']

—

Sets the initial crop region.

initialFocalPoint

{ x: number; y: number }

—

Sets the initial focal point by percentage.

* An asterisk denotes that a prop is required.

Accessibility

  • Provide meaningful upload alt data so generated-size previews describe the underlying image.
  • Keep file names and metadata available alongside visual thumbnails.
  • Preserve keyboard access when adding custom upload actions.
  • Label destructive removal actions clearly and confirm them when removal cannot be reversed.

Provider requirements

FileDetails and EditUpload rely on upload, translation, and modal behavior supplied by the Admin Panel. PreviewSizes expects the normalized document and upload configuration produced by an upload-enabled Collection. For complete form and persistence behavior, use Upload.

Was this page helpful?

Next

Authentication Overview