Feature: CSS Gradient Low Quality Image Placeholders by nickchomey · Pull Request #2550 · WordPress/performance

nickchomey · 2026-06-25T21:30:19Z

Summary

Note:

This is stacked on/includes #2524, which isn't totally necessary but I think made improvements to the test functions. I can rebase this without any of that if desired.

Relevant technical choices

Implemented the CSS Gradient-based LQIP mechanism described in #2519. Extensive testing was done with various ways to generate the dominant color (the original used ColorThief, which has a php equivalent). On rare occasions, the fancier methods produced somewhat better gradients, but at great processing cost. Ultimately I found that the 1x1 pixel was sufficiently-good - especially given that it is already implemented.

I also changed the GD and Imagick editors to extract the color in linear rgb, as per #2535. Updated some tests to reflect the different results. They all pass for me.

Here's a video that shows the gradients using the previous colorspace (left) and the new colorspace (right), generated by imagick. Generally no difference, but its somewhat better in a few cases.

Kooha-2026-06-25-15-22-14.mp4

Nothing was done to accomodate any sort of transition. To use this, all images would need to be reprocessed. Both the dominant color hex and lqip values are generated and stored in postmeta.

Use of AI Tools

I used Deepseek V4 Flash via Github Copilot to assist with this. I reviewed and iterated on everything.

…sed for initial image processing and dominant colours

…never do anything in any test

…ominant_color_get_dominant_color_data. So not redundant to call it afterwards

…e GD tests tun, though not for imagick)

…t stuff coming in other PR. Also, cleaner to just convert in one place for all editors

github-actions · 2026-06-25T21:30:32Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: nickchomey <nickchomey@git.wordpress.org>
Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

codecov · 2026-06-25T21:40:18Z

Codecov Report

❌ Patch coverage is 76.20818% with 64 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.39%. Comparing base (98437a5) to head (3d68d73).

Files with missing lines	Patch %	Lines
...or-images/class-dominant-color-image-editor-gd.php	57.28%	44 Missing ⚠️
plugins/dominant-color-images/hooks.php	58.33%	10 Missing ⚠️
plugins/dominant-color-images/helper.php	76.00%	6 Missing ⚠️
...ages/class-dominant-color-image-editor-imagick.php	89.18%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            trunk    #2550      +/-   ##
==========================================
+ Coverage   70.10%   70.39%   +0.29%     
==========================================
  Files          91       92       +1     
  Lines        7823     8049     +226     
==========================================
+ Hits         5484     5666     +182     
- Misses       2339     2383      +44

Flag	Coverage Δ
multisite	`70.39% <76.20%> (+0.29%)`	⬆️
single	`36.74% <69.51%> (+1.22%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

westonruter · 2026-06-30T01:14:06Z

+  --lqip-ca: mod(round(down, calc((var(--lqip) + 524288) / 262144)), 4);
+    --lqip-cb: mod(round(down, calc((var(--lqip) + 524288) / 65536)), 4);


Minor: the indentation in this file is not consistently using tabs.

westonruter · 2026-06-30T01:15:43Z

 	 * @since 1.0.0
 	 *
-	 * @return string|WP_Error Dominant hex color string, or an error on failure.
+	 * @return array{r: int, g: int, b: int}|WP_Error RGB values (0-255), or WP_Error on failure.


Can be made more specific, unless this causes problems for PHPStan.

Suggested change

* @return array{r: int, g: int, b: int}|WP_Error RGB values (0-255), or WP_Error on failure.

* @return array{r: int<0, 255>, g: int<0, 255>, b: int<0, 255>}|WP_Error RGB values (0-255), or WP_Error on failure.

westonruter · 2026-06-30T01:18:41Z

 		$processor->set_attribute( 'data-dominant-color', $image_meta['dominant_color'] );

-		$style_attribute = '--dominant-color: #' . $image_meta['dominant_color'] . '; ';
+		$style_attribute = '--dominant-color: #' . esc_attr( $image_meta['dominant_color'] ) . '; ';


Is esc_attr() needed? I don't see why it was needed above either because wp_get_attachment_image() automatically applies esc_attr() on the values. So we can get rid of the esc_attr() calls above too.

Suggested change

$style_attribute = '--dominant-color: #' . esc_attr( $image_meta['dominant_color'] ) . '; ';

$style_attribute = '--dominant-color: #' . $image_meta['dominant_color'] . '; ';

And in the context here, the escaping is handled by the HTML Tag Processor.

westonruter · 2026-06-30T01:19:00Z

@@ -78,7 +82,14 @@ function dominant_color_update_attachment_image_attributes( $attr, WP_Post $atta
 	if ( isset( $image_meta['dominant_color'] ) && is_string( $image_meta['dominant_color'] ) && '' !== $image_meta['dominant_color'] ) {
 		$attr['data-dominant-color'] = esc_attr( $image_meta['dominant_color'] );


Suggested change

$attr['data-dominant-color'] = esc_attr( $image_meta['dominant_color'] );

$attr['data-dominant-color'] = $image_meta['dominant_color'];

westonruter · 2026-06-30T01:19:13Z

 		$attr['data-dominant-color'] = esc_attr( $image_meta['dominant_color'] );
 		$style_attribute             = isset( $attr['style'] ) && is_string( $attr['style'] ) ? $attr['style'] : '';
-		$attr['style']               = '--dominant-color: #' . esc_attr( $image_meta['dominant_color'] ) . ';' . $style_attribute;
+		$style_attribute             = '--dominant-color: #' . esc_attr( $image_meta['dominant_color'] ) . ';' . $style_attribute;


Suggested change

$style_attribute = '--dominant-color: #' . esc_attr( $image_meta['dominant_color'] ) . ';' . $style_attribute;

$style_attribute = '--dominant-color: #' . $image_meta['dominant_color'] . ';' . $style_attribute;

westonruter · 2026-06-30T01:22:43Z

+	 * exactly 6 pixels. Each cell's raw RGB values are returned for use
+	 * in LQIP generation.
+	 *
+	 * @since 1.3.0


Suggested change

* @since 1.3.0

* @since n.e.x.t

westonruter · 2026-06-30T01:23:25Z

+		}
+
+		if ( count( $values ) < 6 ) {
+			return array();


How about returning null in case of an error?

Or rather, what about returning a WP_Error? There is already a WP_Error being thrown away above.

westonruter · 2026-06-30T01:23:46Z

+	 * @return array<int, array{r: int, g: int, b: int}> 6 grid cells as ['r'=>R, 'g'=>G, 'b'=>B].
+	 */
+	public function get_lqip_grid_values(): array {


Suggested change

* @return array<int, array{r: int, g: int, b: int}> 6 grid cells as ['r'=>R, 'g'=>G, 'b'=>B].

*/

public function get_lqip_grid_values(): array {

* @return array<int, array{r: int, g: int, b: int}>

null 6 grid cells as ['r'=>R, 'g'=>G, 'b'=>B], or null on error.

*/

public function get_lqip_grid_values(): ?array {

westonruter · 2026-06-30T01:25:20Z

+/**
+ * Retrieves attachment metadata for an image attachment.
+ *
+ * @since 1.0.0


is this right?

Suggested change

* @since 1.0.0

* @since n.e.x.t

westonruter · 2026-06-30T01:26:20Z

+	if ( defined( 'DOMINANT_COLOR_LQIP_HOVER' ) && DOMINANT_COLOR_LQIP_HOVER ) {
+		wp_add_inline_style(
+			'dominant-color-lqip',
+			'[style*="--lqip:"]:hover,.force-lqip{object-position:999px 999px}'
+		);
+	}


Is this just for testing?

nickchomey added 12 commits June 25, 2026 13:13

allow falling back to original image if no subsizes available

361237b

always override core image editor classes, such that same editor is u…

7a8e195

…sed for initial image processing and dominant colours

remove redundant fn call

f90be5c

abstract the get metadata functions

e324697

Remove unnecessary wp_maybe_generate_attachment_metadata calls. They …

7eac0d9

…never do anything in any test

use create rather than create_upload_object, which prevents calling d…

87e984d

…ominant_color_get_dominant_color_data. So not redundant to call it afterwards

require the editor classes, just in case (seems to be missing when th…

8bedb20

…e GD tests tun, though not for imagick)

implement GD tests

76441fc

return raw rgb rather than hex. This will facilitate the lqip gradien…

0d8dc2d

…t stuff coming in other PR. Also, cleaner to just convert in one place for all editors

fix linting

30c680c

Implement Blurhash-like CSS Gradient approach for LQIP

64862de

average pixels in linear light - fix WordPress#2535

80fd750

github-actions Bot added the [Plugin] Image Placeholders Issues for the Image Placeholders plugin (formerly Dominant Color Images) label Jun 25, 2026

nickchomey added 2 commits June 25, 2026 15:42

fix formatting and linting

ce53cb9

fix plugin check

3d68d73

westonruter requested changes Jun 30, 2026

View reviewed changes

		--lqip-ca: mod(round(down, calc((var(--lqip) + 524288) / 262144)), 4);
		--lqip-cb: mod(round(down, calc((var(--lqip) + 524288) / 65536)), 4);

	* @return array{r: int, g: int, b: int}\|WP_Error RGB values (0-255), or WP_Error on failure.
	* @return array{r: int<0, 255>, g: int<0, 255>, b: int<0, 255>}\|WP_Error RGB values (0-255), or WP_Error on failure.

	$style_attribute = '--dominant-color: #' . esc_attr( $image_meta['dominant_color'] ) . '; ';
	$style_attribute = '--dominant-color: #' . $image_meta['dominant_color'] . '; ';

		@@ -78,7 +82,14 @@ function dominant_color_update_attachment_image_attributes( $attr, WP_Post $atta
		if ( isset( $image_meta['dominant_color'] ) && is_string( $image_meta['dominant_color'] ) && '' !== $image_meta['dominant_color'] ) {
		$attr['data-dominant-color'] = esc_attr( $image_meta['dominant_color'] );

	$attr['data-dominant-color'] = esc_attr( $image_meta['dominant_color'] );
	$attr['data-dominant-color'] = $image_meta['dominant_color'];

Uh oh!

Conversation

nickchomey commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Note:

Relevant technical choices

Use of AI Tools

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

codecov Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nickchomey commented Jun 25, 2026 •

edited

Loading

codecov Bot commented Jun 25, 2026 •

edited

Loading