hirasso/focal-point-picker

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

v1.3.8 2025-02-14 13:29 UTC

Requires

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

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• symfony/var-dumper: ^7.1

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%);
}