Crop Mode

Crop mode controls how the image is aligned when fit=crop is set. The w and h parameters define the output dimensions. Multiple values can be combined with a comma to form a fallback chain — imgix applies each value in order and stops at the first successful match. If no value is set or no match is found, the default is a centered crop.

DefaultDirectionalFacesFocal PointEntropyEdgesAutoObject Class

When no crop value is set, imgix crops from the center of the image. fit=crop scales the image to fill the output dimensions exactly, keeping the center portion. Use this as a baseline to compare the effect of other crop values.

https://static-c.imgix.net/woman.jpg?w=320&h=320&fit=crop&q=90

Object-Aware Cropping

crop=auto and crop=<object class> work differently from the other crop values above: instead of a fixed strategy (an edge, a coordinate, an image-wide score), they run subject detection over the image and anchor the crop to whatever they find.

Automatic subject detection (crop=auto)

crop=auto is the recommended crop mode for most scenarios — it requires no manual configuration and adapts to whatever subject is most visually important in the image. crop=auto analyzes the image and automatically selects the most visually important subject as the crop anchor. Detection considers:

• People
• Vehicles — bicycles, cars, motorcycles, airplanes, buses, trains, trucks, boats
• Animals — birds, cats, dogs, horses, sheep, cows, elephants, bears, zebras, giraffes

Faces are weighted more heavily than other subject types — a prominent face takes precedence over a much larger vehicle in the same frame. When multiple compatible subjects are detected, imgix attempts to frame as many as possible before falling back to the single highest-scoring subject.

crop=auto requires fit=crop or fit=min. A URL with crop=auto but no compatible fit value produces a centered crop.

Object class detection (crop=<object class>)

Any of the 80 COCO object class names can be used as a crop value to focus on a detected instance of that class — for example, crop=car, crop=dog, or crop=person. The full list, grouped by category:

The 12 COCO supercategories below are also valid and pool all of their member classes (the person category above has no separate supercategory value — use crop=person directly):

vehicle, animal, food, furniture, electronic, accessory, sports, kitchen, appliance, outdoor, indoor

For example, crop=vehicle focuses whichever vehicle type the detector identifies.

• Class names are case-insensitive.
• Multi-word class names use + or a URL-encoded space — for example, crop=dining+table.
• There is no minimum size floor for named class crops relative to the frame; a car at 2% of the frame is still the anchor if it’s the only car detected.
• If no matching subject is detected, the crop continues through the fallback chain (if one is set) and ultimately defaults to centered — never an error.

Fallback chains with object-aware values

auto and <object class> values can be chained with a comma like any other crop value:

• crop=car,vehicle — focuses a car first, then falls back to any vehicle
• crop=car,auto — falls back to general subject detection
• crop=car,entropy — falls back to entropy scoring

Known Limitations

• rot=90 fallback: When rot=90 is applied, crop=auto and crop=<class> fall back to a centered crop. Rotation is applied to the image pixels before detection runs, and the detection models are trained on upright imagery. rot=180, rot=270, and the or parameter (EXIF-based orientation) all work correctly. Use or= for orientation correction where possible. Note that crop=faces behaves identically under rot=90.
• Small sources: Sources smaller than 64px on either side skip detection entirely and fall back to a centered crop.
• Animated sources: Object-aware crop modes are accepted on animated GIF sources but subject detection is not optimized for animated content.