2018 - 2020, WordPress plugin

ACF Image Aspect Ratio Crop


ACF Image Aspect Ratio Crop is a field for Advanced Custom Fields, a WordPress framework for adding custom data fields to posts, pages, and custom content types.

Image Aspect Ratio Crop works similarly to the normal ACF image field but it allows you to set a specific aspect ratio for the image. The user can use a crop too to select which area of the image they want to display.


When working on WordPress sites, the design often has fixed dimensions for elements, for example a grid of news items need to have fixed height, otherwise the design will break.

In the old days of fixed desktop layouts, you could just add a new image size to WordPress and image would be scaled and cropped to the correct size. With responsive design, retina displays and mobile screens, things are more difficult.

Think about aspect ratios, not pixel sizes

I’m a firm believer that when it comes to images, aspect ratio matters more than fixed pixel size.

Pixel-based WordPress thumbnail sizes are inflexible. Let’s say create 16:9 aspect ratio thumbnail in sizes 750×421, 1080×607 and 1440×810. Let’s say a client uploads a 1439×1079 4:3 image. Since its less than 1440 pixels, WordPress thumbnail functionality will ignore it and create only 750×421 and 1080×607 thumbnails. All those extra pixels in the original image go to waste.

ACF Image Aspect Ratio Crop enables proportional resizing instead of cropping to specific pixel sizes. Just make the crop field a 16:9 image. You can then specify the 750, 1080, and 1440 wide thumbnail sizes in WordPress, without a height. The plugin will crop the hypothetical 1439×1079 4:3 image to 1439×809 16:9 image which you can use in the 16:9 element because it matches the aspect ratio. 1080×607 and 750×421 thumbnails will also be generated.

This way you get all possible pixels in the resulting image.

More control for the crop result

ACF Image Aspect Ratio Crop gives clients more control over how images appear on the site. Automatic cropping is always hit-or-miss. If you have a square element on your site for a contact person and you upload a portrait image, the automatic cropping might cut off that person’s head which is a less-than-stellar end result.

The client would have to use a photo editor like Photoshop to edit the image beforehand or use the image editor buried deep in the WordPress dashboard to crop the image to a manually specified aspect ratio.

With ACF Image Aspect Ratio, the cropping can be done easily and quickly in context.


I originally used a ACF field called Advanced Custom Fields: Image Crop Add-on which worked really well, however, this plugin was centered around pixel sizes and I wanted the option to use an aspect ratio instead.

So I forked the plugin and added an option to use an aspect ratio. Unfortunately, the plugin was not very actively supported and the pull request was not merged.

I eventually created a new plugin from scratch called ACF Image Aspect Ratio Crop which operated on the basis of aspect ratio instead of pixel size. The plugin was first released in 2018. It was meant to be an alternative to the original plugin but since there haven’t been any updates to the plugin for 3 years (as of 2020) and the plugin does not function correctly in the latest ACF versions, ACF Image Aspect Ratio became de-facto plugin for cropping images Advanced Custom Fields.

I still owe a lot to the original plugin – how this plugin operates is very much inspired by it.

Because so many people were using the plugin, many people wanted more options like using a pixel size instead of an aspect ratio so I implemented this feature into the plugin.

Originally, due to an oversight, the plugin did not have the height and width fields set as required in the field admin so some people were actually using the field as a free crop field by not specifying these fields. I got some backlash after I later set the width and height to required. Because of this unexpected use case, the feature was later added to the plugin in an official capacity.

One of the most requested features was the front-end image crop. With ACF it’s possible not only to create forms for WordPress administrators but also to create forms on the front-end for site visitors to fill.

Because of how the WordPress permission system works, the plugin did not support this use case out of the box. However, because this feature was so highly sought after, I spent some time implementing front-end image crop using the WordPress REST API and it was released in plugin version 5.0.0.


As of December 2020, ACF Image Aspect Ratio Crop has been downloaded over 68 000 times and is being used on over 10 000 active WordPress sites, including some high-profile ones. Thanks to the community, it’s been translated into 7 different languages. This is my most popular plugin and it has been undoubtedly a success. I will continue updating it so it will be compatible with future versions of WordPress and Advanced Custom Fields.

I have tons of features I’d like to add but at some point, I will have to refactor the plugin to a more modular structure. Now it’s basically a single PHP file with all features appended to it. What was once simple has grown in complexity and to be able to tackle the technical debt, a rewrite is in order.

One thing will be sure: this plugin is primary geared towards aspect ratios rather than pixel sizes and this won’t change in the future.

Give the plugin a go on the WordPress plugin directory and check out the code on GitHub.