Payload Image Cropper

Usage

Single-Size Crops

A single-size crop produces one output file per preset. Use this when each layout needs its own crop region (e.g. desktop hero vs mobile hero).

  1. 1

    Define crops with width and height

    typescript
    import { cropImageField } from 'payload-plugin-image-cropper'

cropImageField({
  name: 'heroImage',
  label: 'Hero Image',
  crops: [
    {
      name: 'desktop',
      label: 'Desktop (16:9)',
      width: 1920,
      height: 1080,
      aspectRatio: 16 / 9,
      format: 'webp',
      quality: 85,
    },
    {
      name: 'mobile',
      label: 'Mobile (4:5)',
      width: 828,
      height: 1035,
      aspectRatio: 4 / 5,
    },
  ],
})
  2. 2

    Understand each option

    name — machine-readable key stored in cropData and generatedUrls. label — tab label shown in the crop modal. width / height — output dimensions in pixels. aspectRatio — constrains the crop handle (e.g. 16 / 9). format — webp (default), jpeg, or png. quality — Sharp quality 1–100 (default 80; ignored for PNG).

  3. 3

    Editor workflow

    Select or upload a source image. Open the crop modal — each crop appears as a tab. Adjust the region for each preset. Save the document — Sharp generates one file per crop.

  4. 4

    Read URLs in the frontend

    typescript
    import { getCropUrl, resolveMediaCrop } from 'payload-plugin-image-cropper/utilities'

const desktopUrl = getCropUrl(post.heroImage, 'desktop')
const mobileUrl = getCropUrl(post.heroImage, 'mobile')
const media = resolveMediaCrop(post.heroImage, 'mobile')

If no crop exists yet, getCropUrl falls back to the original image URL.