Payload Image Cropper

Usage

Multi-Size Crops

Multi-size crops let editors crop once and generate multiple resolutions from the same region — ideal for responsive card images.

  1. 1

    Use sizes instead of width / height

    typescript
    cropImageField({
  name: 'cardImage',
  label: 'Card Image',
  crops: [
    {
      name: 'card',
      label: 'Card (16:9)',
      aspectRatio: 16 / 9,
      sizes: [
        { name: 'lg', label: 'Large (desktop)', width: 1200, height: 675 },
        { name: 'md', label: 'Medium (tablet)', width: 768, height: 432 },
        { name: 'sm', label: 'Small (mobile)', width: 390, height: 219 },
      ],
    },
  ],
})
  2. 2

    Understand compound keys

    URLs are stored as {cropName}.{sizeName}: card.lg, card.md, card.sm. width/height and sizes are mutually exclusive on a crop definition.

  3. 3

    Read URLs in the frontend

    typescript
    const lgUrl = getCropUrl(post.cardImage, 'card', 'lg')
const mdUrl = getCropUrl(post.cardImage, 'card', 'md')
const smUrl = getCropUrl(post.cardImage, 'card', 'sm')

// Shorthand — equivalent to above
const lgUrl = getCropUrl(post.cardImage, 'card.lg')
  4. 4

    Responsive HTML

    typescript
    <picture>
  <source media="(min-width: 1024px)" srcset={lgUrl} />
  <source media="(min-width: 640px)" srcset={mdUrl} />
  <img src={smUrl} alt="Card image" />
</picture>
  5. 5

    Next.js Image with custom loader

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

function cardImageLoader({ width }: { width: number }) {
  if (width <= 390) return getCropUrl(post.cardImage, 'card', 'sm')
  if (width <= 768) return getCropUrl(post.cardImage, 'card', 'md')
  return getCropUrl(post.cardImage, 'card', 'lg')
}

<Image
  loader={cardImageLoader}
  src={getCropUrl(post.cardImage, 'card', 'lg')}
  alt="Card"
  width={1200}
  height={675}
  sizes="(max-width: 390px) 390px, (max-width: 768px) 768px, 1200px"
/>