Payload Image Cropper
Payload CMS Plugin

Image Cropping,
perfected.

A powerful, seamless, and un-opinionated image cropper plugin for Payload CMS. Empower your content editors to frame images exactly as intended without ever leaving the admin panel.

Get Started Star on GitHub
1920 × 1080 px

Documentation

Comprehensive guides and references to help you extend Payload CMS with powerful image cropping capabilities.

Getting Started

Install and set up the plugin in your Payload project.

Configuration

Explore plugin options and field-level settings for custom aspect ratios.

Frontend Integration

See the data shape and learn how to display cropped images in your app.

API Reference

Detailed breakdown of the CropDefinition interfaces and metadata structure.

View all documentation

Quick Installation

Get up and running in minutes. Install the package and register the plugin in your Payload config.

1. Install the package

Terminal
npm install payload-plugin-image-cropper
# or
yarn add payload-plugin-image-cropper
# or
pnpm add payload-plugin-image-cropper

2. Register the plugin

Add it to your payload.config.ts

payload.config.ts
import { buildConfig } from 'payload/config'
import { imageCropper } from 'payload-plugin-image-cropper'

export default buildConfig({
  plugins: [
    imageCropper({
      // Your configuration options here
    })
  ]
})

3. Add to a collection

Use the cropImageField in your Media collection

collections/Media.ts
import { CollectionConfig } from 'payload/types'
import { cropImageField } from 'payload-plugin-image-cropper'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: true,
  fields: [
    cropImageField({
      name: 'heroCrop',
      options: { aspectRatio: 16 / 9 },
    }),
  ],
}