# Upload Helpers

Source: https://payloadcms.com/docs/ui-components/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

```tsx
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.

**Implementation**

```tsx
<FileDetails
  collectionSlug="media"
  doc={doc}
  hideRemoveFile
  uploadConfig={uploadConfig}
/>
```

**Styling**

Customize the FileDetails surface and thumbnail while preserving its metadata, copy, adjustment, and removal behavior.

```css
.file-details {
  background: #f9f8ff;
  border: 1px solid #c8c0ff;
  border-radius: 8px;
}

.file-details__thumbnail {
  border-radius: 6px;
}
```

- `background`: File summary surface.
- `border`: File summary outline.
- `border-radius`: Summary and thumbnail corner radius.

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.

**Implementation**

```tsx
<PreviewSizes doc={doc} uploadConfig={uploadConfig} />
```

**Styling**

Target the selected size and structural regions to align the PreviewSizes browser with a project’s media treatment.

```css
.preview-sizes__sizeOption:hover,
.preview-sizes--selected {
  background: #f3f1ff;
}

.preview-sizes__imageWrap {
  border-color: #c8c0ff;
}
```

- `background`: Selected and hovered size surface.
- `border-color`: Divider between the preview and size list.

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.

```tsx
<EditUpload
  fileName={doc.filename}
  fileSrc={doc.url}
  initialCrop={doc.crop}
  initialFocalPoint={doc.focalPoint}
  onSave={(uploadEdits) => updateUploadEdits(uploadEdits)}
  showCrop
  showFocalPoint
/>
```

`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`](/docs/v3/ui-components/upload.md).