Skip to main content

Crop

Use the crop transformation to extract a smaller region or target aspect ratio from a delivered image variant.

Overview​

Cropping is useful when the same source image needs to fit cards, thumbnails, previews, banners, or social images. Use coordinate-based crops when you know the exact source region to extract, or use Gravity when Imgwire needs to choose which part of the image to keep for a target aspect ratio.

Syntax​

FieldValue
Canonical parametercrop
Aliasc
Value syntaxwidth:height[:gravity], x:y:width:height[:gravity], or an SDK object with width, height, optional x, y, and gravity

Example​

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?crop=520:200:520:520&width=420&format=auto&quality=auto
image.url({
  crop: '520:200:520:520',
  width: 420,
  format: 'auto',
  quality: 'auto',
});
imgwire images url img_123 --crop 520:200:520:520 --width 420 --format auto --quality auto

Live examples​

These examples use x:y:width:height crops to extract smaller regions from the original image, then resize the extracted region for display.

Original transformation demo image

Left detailCenter detailRight detail
Small region cropped from the left side of the demo imageSmall region cropped from the center of the demo imageSmall region cropped from the right side of the demo image

Smart Crop: Gravity Attention​

Use Gravity: Attention as Imgwire's smart crop capability when you know the target crop size but do not want to hardcode x and y coordinates. In URL syntax, this is the attention gravity value at the end of the crop rule.

attention tells Imgwire to use content-aware focus for the retained region. It is useful for user uploads, generated images, social cards, and thumbnails where the important part of the image may not always be centered.

crop=640:360:attention
image.url({
  crop: '640:360:attention',
  format: 'auto',
  quality: 'auto',
});

Use coordinate crops like crop=520:200:520:520 when you know the exact region. Use smart crop with Gravity: Attention when you want Imgwire to choose the strongest region for a target aspect ratio.

Center cropSmart crop with Gravity: Attention
Wide off-center astronaut portrait cropped with center gravityWide off-center astronaut portrait smart cropped with attention gravity

Best practices​

  • Use crop for fixed-ratio layouts such as cards, avatars, thumbnails, and hero slots.
  • Use Gravity: Attention for smart crops when source composition varies.
  • Choose gravity intentionally so important content stays visible.
  • Use stable crop dimensions for repeated UI components.
  • Pair crops with format=auto and quality=auto for public delivery.

Common mistakes​

  • Cropping without considering the subject's location.
  • Using crop when proportional resizing would preserve the image better.
  • Forgetting to test crops on real uploaded content with different compositions.

Last updated at: May 9, 2026