hirasso/focal-point-picker

Zero-dependency custom focal point picker for your WordPress images 🎯

v1.4.0 2025-10-30 19:28 UTC

Requires

• php: >=8.2
• composer/installers: ^2.3

Requires (Dev)

• laravel/pint: ^1.25
• phpstan/phpstan: ^2.1
• roots/wordpress: ^6.8
• symfony/var-dumper: ^7.1
• wp-cli/wp-cli: ^2.12

GPL-3.0-or-later

• Rasso Hilber

README

Zero-dependency custom focal point picker for your WordPress images 🎯

Installation

Via Composer (recommended):

1. Install the plugin:

composer require hirasso/focal-point-picker

1. Activate the plugin manually or using WP CLI:

wp plugin activate focal-point-picker

Manually:

1. Download and extract the plugin
2. Copy the focal-point-picker folder into your wp-content/plugins folder
3. Activate the plugin via the plugins admin page – Done!
4. Handle updates via afragen/git-updater

Data structure

You can retrieve the focal point for an image like this:

$focalPoint = fcp_get_focalpoint($imageID);
var_dump($focalPoint);

Output:

object(FocalPointPicker\FocalPoint)#2796 (4) {
  ["left"]=>
  float(0.5)
  ["top"]=>
  float(0.5)
  ["leftPercent"]=>
  float(50)
  ["topPercent"]=>
  float(50)
  ["x"]=>
  float(0.5)
  ["y"]=>
  float(0.5)
  ["xPercent"]=>
  float(50)
  ["yPercent"]=>
  float(50)
}

Usage in your templates

Object Position

<?php

$imageID = 1234;
$imageSRC = wp_get_attachment_image_src($imageID, 'large');
$focus = fcp_get_focalpoint($imageID);

?>

<style>
#my-image {
  height: 300px;
  width: 600px;
  position: relative;
}
#my-image img {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}
</style>

<div id="my-image">
  <img
    src="<?= $imageSRC[0] ?>"
    style="object-position: <?= $focus->leftPercent ?? 50 ?>% <?= $focus->topPercent ?? 50 ?>%;">
</div>

Background Position

<?php

$imageID = 1234;
$imageSRC = wp_get_attachment_image_src($imageID, 'large');
$focus = fcp_get_focalpoint($imageID);

?>

<style>
#my-image {
  background-image: url('<?php echo $imageSRC[0]; ?>');
  background-size: cover;
  height: 300px;
  width: 600px;
}
</style>

<div
  id="my-image"
  style="background-position: <?= $focus->leftPercent ?? 50 ?>% <?= $focus->topPercent ?? 50 ?>%;">
</div>

Using wp_get_attachment_image

If you are making use of the WordPress function wp_get_attachment_image(), the plugin will automatically inject a class focal-point-image and two custom css properties for you to use:

<img
  width="150"
  height="150"
  src="http://example.com/wp-content/uploads/bear-150x150.png"
+ class="attachment-thumbnail size-thumbnail focal-point-image"
  alt=""
  decoding="async"
  loading="lazy"
+ style="--focal-point-left: 0.46; --focal-point-top: 0.2"
>

You can use that like this, for example:

.focal-point-image {
  aspect-ratio: 16/7; /** or whatever you like */
  height: auto;
  object-fit: cover;
  object-position:
    calc(var(--focal-point-left, 0.5) * 100%)
    calc(var(--focal-point-top, 0.5) * 100%);
}

Filters

The default position of the focal point can be customized using filters:

use Hirasso\FocalPointPicker\Position;

/** center top. Great for preserving faces in cropped images */
add_filter(
    'hirasso/fcp/default-position',
    fn() => new Position(left: 0.5, top: 0)
);

/** or simply: */
add_filter(
    'hirasso/fcp/default-position',
    fn() => new Position(top: 0)
);

/** etc... */

This might come in handy if you have many photographs where the eyes of people are at the top of the image somewhere and you don't want to adjust them all manually.

WP_CLI Interface

fcp apply-default-position

Apply the default position to existing images:

# apply the default position to a selection of images:
wp fcp apply-default-position 23 42 999

# apply the default position to ALL of your images:
wp fcp apply-default-position --all

# apply the default position to ALL of your images, skipping the confirmation prompt (for scripting)
wp fcp apply-default-position --all --yes