Crop Images

About the crop feature

What is it? Crop cuts an original JPG or PNG image before delivery. Specify area and location using query strings.

Example: Origin hosts 750×1150 px image. With crop 500,400 from center, users get 500×400 version. Origin unchanged.

Enable the crop feature

Crop is included in the Image Optimizer service. Add query parameters to image URLs.

Use crop

Add query strings to image URLs:

image.jpg?crop=16:9
image.jpg?crop=400,300
image.jpg?crop=400,300,x100,y50

Crop parameters

1. Aspect ratio crop

?crop=W:H

Crops to aspect ratio from center. Examples: 16:9, 1:1, 4:3

<img src="img.jpg?crop=16:9" alt="Widescreen" />
<img src="img.jpg?crop=1:1" alt="Square" />

2. Dimensions from center

?crop=W,H

Crops specific dimensions from center.

<img src="img.jpg?crop=400,300" alt="Cropped" />

3. Pixel position

?crop=W,H,xN,yN

Top-left corner at specific pixel position.

<img src="img.jpg?crop=400,300,x100,y50" alt="Cropped" />

4. Percentage position

?crop=W,H,xNp,yNp

Top-left corner at percentage of image dimensions.

<img src="img.jpg?crop=400,300,x25p,y20p" alt="Cropped" />

5. Offset from center

?crop=W,H,offset-xN,offset-yN

Offset from center by percentage (positive = right/down, negative = left/up).

<img src="img.jpg?crop=400,400,offset-x10,offset-y-5" alt="Cropped" />

6. Combined positioning

Mix different positioning methods for X and Y:

<img src="img.jpg?crop=200,100,x107,offset-y20" alt="Combined" />

Common use cases

<!-- Social media -->
<img src="photo.jpg?crop=1:1" alt="Instagram" />
<img src="photo.jpg?crop=9:16" alt="Story" />

<!-- Thumbnails -->
<img src="photo.jpg?crop=200,200" alt="Thumbnail" />

<!-- Hero images -->
<img src="hero.jpg?crop=21:9" alt="Hero" />

<!-- Resize + crop -->
<img src="photo.jpg?width=1200&crop=16:9" alt="Optimized" />

<!-- Crop + WebP -->
<img src="photo.jpg?crop=16:9&fmt=webp" alt="Optimized" />

Responsive crops

<picture>
  <source srcset="image.jpg?crop=21:9" media="(min-width: 1200px)" />
  <source srcset="image.jpg?crop=16:9" media="(min-width: 768px)" />
  <img src="image.jpg?crop=1:1" alt="Responsive" />
</picture>

Check HTTP headers

curl -I https://your-cdn.com/image.jpg?crop=16:9

Expected: X-Img-Operations: cropping

Limitations

Cannot exceed original dimensions

Crop dimensions must be ≤ original image dimensions.

Original: 1000×1000 pixels
✅ Valid: ?crop=500,500
❌ Invalid: ?crop=1500,1500

Error: Crop skipped, error logged; remaining operations continue.

See limitations.md for details.

Processing order

Resize - First (if specified)
Crop - Second
Format + Quality - Last

Performance

Operation	Time	Status
Crop	`<100ms`	✅ Excellent
Resize + Crop	`<150ms`	✅ Excellent

Troubleshooting

Crop not applied: Check syntax (?crop=16:9 or ?crop=400,300) Dimensions exceed error: Reduce crop dimensions to fit within original Unexpected position: Check x/y format (pixels x100 vs percentage x100p vs offset offset-x10)