---
title: "Media and image optimization"
description: "The uploads collection, file guard, ownership and uploads.imageOptimization."
requested_language: ar
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/ar/next/payload/content/media
version: unreleased (main)
docs_index: https://docs.systhema.app/ar/next/llms.txt
---
> This page isn't translated yet. Showing English.


Uploaded files live in the uploads collection. Its slug and storage directory are set with the `uploads` plugin option (`uploads: { slug: 'media', staticDir: 'media' }`).

## The uploads collection

The default slug is `uploads`, with local storage under `storage/uploads`. Folders and trash are enabled by default. `alt` stores the image's alternative text; `uploadedBy` stores its owner. Relationships in built-in fields follow a configured uploads slug.

![The Uploads collection with filenames, alternative text and MIME types](./images/uploads.light.webp)

### File guard

`FileGuard` checks a selected Admin file before submission. It clears files above `uploads.maxFileSize` or outside `uploads.allowedMimeTypes` and shows an error. The default maximum is 100 MiB. MIME entries match prefixes; an empty list allows all types. Unknown browser MIME types bypass that client-side MIME check.

A server `beforeOperation` hook rejects oversized create/update uploads before image processing or storage, with a 400 response. Set `maxFileSize: 0` to remove the size limit. `allowedMimeTypes` is the Admin check, so do not treat it as server-side MIME validation for arbitrary API uploads.

### Ownership and access

Creation records the signed-in user's ID in `uploadedBy`. Public reads are allowed so website media can load. Signed-in users with `uploads.read` see all uploads; other signed-in users see only their own. Update/delete capabilities allow changes to any upload; without them, access is filtered to the user's own uploads. Changing ownership itself requires `uploads.update` and the sidebar field is read-only in Admin.

Keep useful alternative text on informative images. The Image block renders an empty alt attribute when the upload has no authored alt.

Uploading requires the `uploads.create` capability; see [Access control](https://docs.systhema.app/ar/next/payload/access-control.md). Changing an upload's alt text revalidates every page; see [Revalidation](https://docs.systhema.app/ar/next/payload/frontend/revalidation.md).

## Image optimization

With the defaults, the maximum width is 2560 pixels and JPEG/PNG quality is 60. Uploaded JPEGs and PNGs are resized to a maximum width and re-compressed before Payload writes them; a PNG with no real transparency is converted to JPEG (filename and mime type follow). Set `uploads: { imageOptimization: false }` to turn it off, or pass `{ maxWidth, jpegQuality, convertPngToJpeg, pngQuality }` to tune it.

**It does not run on client uploads.** With Payload's `clientUploads` the browser sends the file straight to storage, so by the time the document is created the object already exists under its original name — `@payloadcms/plugin-cloud-storage` skips re-uploading it, and re-encoding or renaming it here would leave the document pointing at an object that was never written. Optimize those images before upload, or in your storage pipeline.

## Related

- [Image block](https://docs.systhema.app/ar/next/payload/blocks/image.md)
- [Video block](https://docs.systhema.app/ar/next/payload/blocks/video.md)
- [Plugin options](https://docs.systhema.app/ar/next/payload/plugin-options.md)