Adding and managing images

All the images on your site are stored in one place: the Media collection in Payload. When you place an image on a page, you're picking it from Media. This means you can reuse the same image in several places, and if you replace it, it updates everywhere it's used.

Uploading a new image

1. In the sidebar, click Media.
2. Click Create New (top-right).
3. Drag your image onto the upload area, or click to browse.
4. Fill in the fields:
   • Alt text — a short description of what's in the image. This is important for accessibility (screen readers) and SEO. Example: "A mechanic installing a hydraulic hose on a tractor." Don't just type the filename.
   • Caption (optional) — text shown beneath the image on pages that use it.
5. Click Save.

Image size and format

• Format: JPEG for photos, PNG for logos and graphics with transparency, WebP if you have it (it's smaller and faster).
• Size: aim for around 2000 pixels on the longest edge for hero/banner images, 1200 pixels for most others. Payload automatically generates smaller versions for different screen sizes.
• File size: keep files under 500 KB where possible — smaller is faster for visitors. The platform accepts files up to 50 MB per upload, but anything above a megabyte is overkill for a web image and will slow the site down.

If your image is bigger than it needs to be, tools like TinyPNG or the export settings in your design software can shrink it without a visible drop in quality.

Finding an image you've already uploaded

In the Media list, use the search bar at the top. It searches by filename and by alt text — so if you wrote good alt text, you'll find images easily.

You can also filter by upload date using the column headers.

Using an image on a page

When you're editing a page or block that has an image field:

1. Click the image field (or the Add Media button).
2. A dialog opens showing your Media library.
3. Either select an existing image or click Upload to add a new one.
4. Click Save.

Replacing an image everywhere it's used

This is where Media really helps. If you need to update a logo or a hero image that's used on several pages:

1. Go to Media and click the image you want to replace.
2. Click Edit and upload the new file in the same record.
3. Save.

The new image now shows up automatically on every page that used the old one. You don't need to edit each page individually.

Deleting an image

In the Media list, click the checkbox next to the image and choose Delete. Payload will warn you if the image is currently used on any pages. Don't delete an image that's in use — the pages that reference it will show a broken image to your customers. Replace it first, then delete.