PHPackages                             doubleedesign/acf-advanced-image-field - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. doubleedesign/acf-advanced-image-field

ActiveWordpress-plugin[Utility & Helpers](/categories/utility)

doubleedesign/acf-advanced-image-field
======================================

Enhanced image field for Advanced Custom Fields with aspect ratio and focal point settings + real-time in-editor preview.

0.0.3(4mo ago)161PHP

Since Dec 22Pushed 4mo agoCompare

[ Source](https://github.com/doubleedesign/acf-advanced-image-field)[ Packagist](https://packagist.org/packages/doubleedesign/acf-advanced-image-field)[ RSS](/packages/doubleedesign-acf-advanced-image-field/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)DependenciesVersions (4)Used By (0)

Advanced Image Field for ACF
============================

[](#advanced-image-field-for-acf)

An [Advanced Custom Fields](https://www.advancedcustomfields.com/) field type providing in-editor options and real-time preview of aspect ratio and focal point selection.

Uses the built-in image, group, number, and select fields to create a more advanced image field while leveraging ACF's native editor UI and back-end processing functionality. It also utilises WordPress/ClassicPress's built-in attachment meta for alt text, caption, and title values to keep data consistent across the site, avoid duplicate/redundant data being stored in the database and potentially causing confusion for editors.

[![editor-screenshot.png](docs/editor-screenshot.png)](docs/editor-screenshot.png)

*This plugin is not affiliated with or endorsed by WPEngine, the owners of ACF.*

Status
------

[](#status)

This is an alpha release that has been minimally tested for use as a standalone field, within a flexible content field, or within an ACF block.

I have no reason to think it wouldn't also work with repeaters but have not tested this. More extensive and automated testing will be carried out when I continue work on this.

Installation
------------

[](#installation)

Zip package still to come. In the meantime, you can fork/clone/download this repo and place the `acf-advanced-image-field` folder in your WordPress `wp-content/plugins` directory and activate it as normal.

Usage
-----

[](#usage)

The field returns an associative array value for use in your templates, with the following fields:

KeyTypeDescription`image_id``int`The attachment ID`url``string`The URL of the image, scaled to 1200px max on its longest side`aspect_ratio``AspectRatio`The selected aspect ratio`focal_point``array{x: int, y: int}`The selected focal point coordinates`offset``array{x: int, y: int}`The percentage offsets required to position the image to suit the focal point`alt``string`The alt text set on the attachment`caption``string`The caption set on the attachment`title``string`The title of the attachmentThe `AspectRatio` type is an enum that matches keywords to common aspect ratios to ensure only valid values are used.

```
enum AspectRatio: string {
	case STANDARD = '4:3';
	case PORTRAIT = '3:4';
	case SQUARE = '1:1';
	case WIDE = '16:9';
	case TALL = '9:16';
	case CLASSIC = '3:2';
	case CLASSIC_PORTRAIT = '2:3';
}
```

The plugin registers an image size in WordPress, called `image_advanced_resized` (and a constant for it, `ACF_ADVANCED_IMAGE_FIELD_SIZE`), which scales larger images down to 1200px on their longest side. This is so that the image can be positioned within the frame according to its settings without additional images being generated every time the settings are changed, without potentially loading huge images on the front-end where it is not necessary. This resized image is the one returned by default when fetching the field value.

This plugin does not provide the HTML or CSS required to make the images format correctly on the front-end. You will need to do this in your theme.

**Example front-end code to come.**

Back-end customisation
----------------------

[](#back-end-customisation)

Developers can add and modify the options available using the `acf_advanced_image_options_fields` filter. By default, it contains the aspect ratio, focal point, and image offset field definitions.

For example, you could add a field like so:

```
add_filter('acf_advanced_image_options_fields', function($fields, $parent_key) {
	array_push($fields, array(
		'key' => $parent_key . '_custom_option',
		'label' => 'Custom Option',
		'name' => 'custom_option',
		'type' => 'text',
		'instructions' => 'A custom option added via the acf_advanced_image_options_fields filter.',
	));

	return $fields;
})
```

You also have access to the existing field definitions, so you can:

- modify things like their labels, instructions, options, and default values,
- remove fields you don't want.

Warning

It is strongly recommended not to change any of the built-in field keys, names, types, or return values as this may break things or have other unintended consequences. If you use the filter to remove a field or change a field key or name (despite the above warning), please be aware that this *will not* remove existing data for the removed/renamed field from the database,

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance76

Regular maintenance activity

Popularity14

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity27

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

3

Last Release

135d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3accb0a797c2fbc03199b7719a63250e5e76e5bbbddaf529b945663c255dfe98?d=identicon)[doubleedesign](/maintainers/doubleedesign)

---

Top Contributors

[![doubleedesign](https://avatars.githubusercontent.com/u/563583?v=4)](https://github.com/doubleedesign "doubleedesign (9 commits)")

---

Tags

advanced-custom-fieldsclassicpress-plugincssjavascriptphpwordpress-plugin

### Embed Badge

![Health badge](/badges/doubleedesign-acf-advanced-image-field/health.svg)

```
[![Health](https://phpackages.com/badges/doubleedesign-acf-advanced-image-field/health.svg)](https://phpackages.com/packages/doubleedesign-acf-advanced-image-field)
```

###  Alternatives

[roots/bedrock-autoloader

An autoloader that enables standard plugins to be required just like must-use plugins

405.6M51](/packages/roots-bedrock-autoloader)[contributte/neonizer

Collection of useful scripts for manipulaton with NEON files. Support composer pre-install / post-install events. Set/get parameters, validate files.

14849.4k](/packages/contributte-neonizer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)