Payload Image Cropper

Getting Started

Quick Start

Minimal setup in four steps.

Minimal setup in four steps.

  1. 1

    Add the plugin

    typescript
    import path from 'path'
import { buildConfig } from 'payload'
import { cropImagePlugin } from 'payload-plugin-image-cropper'
import sharp from 'sharp'

export default buildConfig({
  sharp,
  collections: [
    {
      slug: 'media',
      upload: {
        staticDir: 'public/media',
      },
      fields: [],
    },
  ],
  plugins: [
    cropImagePlugin({
      mediaDir: path.join(process.cwd(), 'public/media'),
    }),
  ],
})
  2. 2

    Add a crop field to a collection

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

{
  slug: 'posts',
  fields: [
    cropImageField({
      name: 'heroImage',
      label: 'Hero Image',
      crops: [
        {
          name: 'desktop',
          label: 'Desktop (16:9)',
          width: 1920,
          height: 1080,
          aspectRatio: 16 / 9,
        },
      ],
    }),
  ],
}
  3. 3

    Crop in the admin

    Open a Post in the admin panel. Select or upload an image in the Hero Image field. Click Crop to open the modal. Adjust the crop region and save the document.

  4. 4

    Use the crop URL in your frontend

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

const url = getCropUrl(post.heroImage, 'desktop')