Fix Color Picker Cursor Shaking Issue

[shail-mehta]

What?

Closes: #80110

When applying a Gradient background to a block and adding a new color stop, moving the color picker cursor inside the color picker box causes the cursor to continuously shake/jitter instead of moving smoothly to the selected position.

Why?

Prevent cursor jitter in the Gradient color picker caused by unstable HSLA values during color updates.

How?

• Use mergeHSLA to preserve HSLA values before generating the hex value.

Testing Instructions

• Create any post/page.
• Add any block (e.g. Paragraph).
• In Block settings, apply a Gradient background.
• On the gradient color bar, click the + (add color stop) button.
• In the color picker that opens, move the color cursor slightly within the picker box.
• See Issue.

Additional Notes

• This only happens while setting the color for the new stop.
• While dragging the cursor, some points shake/jitter and some points remain in place.

Screenshots or screencast

80110.mp4

Use of AI Tools

• Yes

[github-actions]

Size Change: +261 B (0%)

Total Size: 7.73 MB

📦 View Changed

Filename	Size	Change
build/scripts/components/index.min.js	272 kB	+261 B (+0.1%)

_{compressed-size-action}

[github-actions]

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: shail-mehta <shailu25@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: noruzzamans <noruzzaman@git.wordpress.org>
Co-authored-by: 3kori <r1k0@git.wordpress.org>
Co-authored-by: SAndrrew <andrewssanya@git.wordpress.org>
Co-authored-by: nikunj8866 <nikunj8866@git.wordpress.org>

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

[github-actions]

Flaky tests detected in 9add89c.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29511257714
📝 Reported issues:

• [Flaky Test] Should navigate inner blocks with arrow keys #39607 in /test/e2e/specs/editor/various/writing-flow.spec.js

[mirka]

Some unit tests that maybe useful here:

• Changing saturation from 50 to 0 at black and white. For example, start at hsl(200, 50%, 0%) and change the saturation control to 0. Assert that the control shows 0, and the onChange doesn't fire because the hex value is the same.
• Controlled-mode test ensuring one callback run per real color change.

[mirka]

State updaters needs to be pure, and this is now running a state updater (setColor) inside a state updater (setInternalHSLA).

[mirka]

Changing saturation or lightness from the HSL controls can also change these values, so this is not enough to conclude that it was a positional drag.

[noruzzamans]

@shail-mehta! Tested this on both trunk and the fix branch — on trunk the cursor visibly shakes/jitters when moving inside the color picker for a new gradient stop, but on this branch it moves smoothly with no jitter. Issue is resolved.

Before:

Screen.Recording.2026-07-14.at.4.40.32.PM.mov

After:

Screen.Recording.2026-07-14.at.4.54.02.PM.mov

[ciampo]

This looks like another symptom of the same color-model synchronization problem, rather than something we should fix with another HSL heuristic.

The history is:

• #35670 and #36941 addressed pointer movement caused by controlled values being converted and echoed back into react-colorful.
• #57555 introduced internal HSLA state because the HSLA → hex → HSLA round trip loses hue and saturation.
• #75157 initially reproduced the jitter with an HSL picker, then eliminated it by keeping the visual picker in its native HSVA model.
• #75493 moved the component to shared HSLA state, but explicitly left this achromatic-boundary snap unresolved. Parallel HSVA state or an upstream fix was suggested.
• #79266 is separately addressing delayed/out-of-order controlled value echoes.

This PR continues the same cycle by trying to infer whether an update came from the visual picker based on which HSL channels changed. That inference is unreliable, and the merged value can actually make react-colorful treat its own update as external and reset the pointer’s saturation.

I think the right direction is to keep the visual picker in HSVA, keep the HSL inputs in HSLA, and explicitly reconcile the two paths when necessary. That addresses the underlying representation mismatch instead of adding another conversion workaround.

The fundamental HSVA/HSLA separation does not need to be completed in this PR, but this PR should at least use a source-specific visual-picker path that cannot affect HSL inputs and preserves the picker's native pointer state. Without that boundary, merging it would trade one visible form of shakiness for another known failure.

[shail-mehta]

Thank you both for the feedback.

I tried to address this issue using a suggested approach. When you have a chance, could you please review it and let me know if you think any further changes or corrections are needed?

[ciampo]

No regression tests were added for the pointer path, HSL controls at black/white, controlled callbacks, or the new-gradient-stop flow. Would you be able to add them?

[shail-mehta]

Thanks for the prompt response. I'll look into it and update the PR accordingly.

[ciampo]

We'll need to move this entry under the new "Unreleased" section.

Let's also potentially reword the entry to be more specific about the fix it tackles, rather than saying controlled echoes cannot reset the pointer generally.

[ciampo]

Still in the wrong section even after the rebase

[shail-mehta]

Thanks for the feedback. I will check all points

[ciampo]

Looks like the CHANGELOG entry is still in the wrong section.

Also, to avoid to continue the back-and-forth, please make sure to review your changes internally and check for new regressions before asking for a new review round 🙏

[ciampo]

colord( hsla ).toHsv() returns h: 0 for achromatic colors even though internalHSLA intentionally retains the user's hue. This leaves the HSL Hue control and the visual picker on different hue planes. Copying hsla.h unconditionally is correct because HSL and HSV share the hue angle; only their saturation/value-lightness coordinates require conversion.

Suggested resolution

[major] The remaining bug is one missing invariant rather than a sign that the state model needs another redesign. HSL and HSV share the same hue angle, so an achromatic conversion should not be allowed to replace the latent HSLA hue with 0. Could we copy hsla.h into HSVA unconditionally and cover leaving both white and mid-gray through the visual surface? I tested the diff below against this head; it fixes both reproductions and the focused suites still pass. With this applied, I am comfortable approving the implementation.

Suggested diff

diff --git a/packages/components/src/color-picker/picker.tsx b/packages/components/src/color-picker/picker.tsx
--- a/packages/components/src/color-picker/picker.tsx
+++ b/packages/components/src/color-picker/picker.tsx
@@ -15,6 +15,9 @@ import type { PickerProps } from './types';
 function toHsva( hsla: PickerProps[ 'hsla' ] ): HsvaColor {
 	return {
 		...colord( hsla ).toHsv(),
+		// HSL and HSV share the hue angle. Color conversion collapses achromatic
+		// hue to 0, but HSLA retains the user's latent hue.
+		h: hsla.h,
 		a: hsla.a,
 	};
 }
diff --git a/packages/components/src/color-picker/test/index.tsx b/packages/components/src/color-picker/test/index.tsx
--- a/packages/components/src/color-picker/test/index.tsx
+++ b/packages/components/src/color-picker/test/index.tsx
@@ -889,6 +889,77 @@ describe( 'ColorPicker', () => {
 			expect( pointer ).toHaveStyle( { top: '0%', left: '0%' } );
 		} );
 
+		it( 'uses the HSL hue when leaving white through the visual surface', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<ControlledColorPicker
+					onChange={ onChange }
+					enableAlpha={ false }
+					initialColor="#cc0000"
+				/>
+			);
+
+			await user.selectOptions( screen.getByRole( 'combobox' ), 'hsl' );
+			const lightnessSlider = screen.getByRole( 'slider', {
+				name: 'Lightness',
+			} );
+			fireEvent.change( lightnessSlider, { target: { value: 100 } } );
+
+			const hueSlider = screen
+				.getAllByRole( 'slider', { name: 'Hue' } )
+				.at( -1 )!;
+			fireEvent.change( hueSlider, { target: { value: 200 } } );
+			await waitFor( () => expect( hueSlider ).toHaveValue( '200' ) );
+
+			const colorSlider = screen.getByRole( 'slider', { name: 'Color' } );
+			mockInteractiveBounds( colorSlider );
+			onChange.mockClear();
+			fireEvent.mouseDown( colorSlider, {
+				buttons: 1,
+				pageX: 50,
+				pageY: 0,
+				clientX: 50,
+				clientY: 0,
+			} );
+
+			expect( onChange ).toHaveBeenLastCalledWith( '#80d4ff' );
+		} );
+
+		it( 'uses the HSL hue when leaving a mid-gray through the visual surface', async () => {
+			const user = userEvent.setup();
+			const onChange = jest.fn();
+
+			render(
+				<ControlledColorPicker
+					onChange={ onChange }
+					enableAlpha={ false }
+					initialColor="#808080"
+				/>
+			);
+
+			await user.selectOptions( screen.getByRole( 'combobox' ), 'hsl' );
+			const hueSlider = screen
+				.getAllByRole( 'slider', { name: 'Hue' } )
+				.at( -1 )!;
+			fireEvent.change( hueSlider, { target: { value: 200 } } );
+			await waitFor( () => expect( hueSlider ).toHaveValue( '200' ) );
+
+			const colorSlider = screen.getByRole( 'slider', { name: 'Color' } );
+			mockInteractiveBounds( colorSlider );
+			onChange.mockClear();
+			fireEvent.mouseDown( colorSlider, {
+				buttons: 1,
+				pageX: 50,
+				pageY: 50,
+				clientX: 50,
+				clientY: 50,
+			} );
+
+			expect( onChange ).toHaveBeenLastCalledWith( '#416c81' );
+		} );
+
 		it( 'updates visual saturation when HSL saturation is edited at black', async () => {
 			const user = userEvent.setup();

[shail-mehta]

Thanks, @ciampo, for the detailed explanation and the suggested diff. I've addressed the feedback in the latest commit.

When you have a chance, could you please take another look?

[ciampo]

🚀 LGTM

[github-actions]

There was a conflict while trying to cherry-pick the commit to the wp/7.1 branch. Please resolve the conflict manually and create a PR to the wp/7.1 branch.

PRs to wp/7.1 are similar to PRs to trunk, but you should base your PR on the wp/7.1 branch instead of trunk.

# Checkout the wp/7.1 branch instead of trunk.
git checkout wp/7.1

# Create a new branch for your PR.
git checkout -b my-branch

# Cherry-pick the commit.
git cherry-pick 46048e6380e389508a29f06194ae99e57dbcfb7e

# Check which files have conflicts.
git status

# Resolve the conflict...
# Add the resolved files to the staging area.
git status
git add .
git cherry-pick --continue

# Push the branch to the repository
git push origin my-branch

# Create a PR and set the base to the wp/7.1 branch.
# See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.

[github-actions]

There was a conflict while trying to cherry-pick the commit to the wp/7.1 branch. Please resolve the conflict manually and create a PR to the wp/7.1 branch.

PRs to wp/7.1 are similar to PRs to trunk, but you should base your PR on the wp/7.1 branch instead of trunk.

# Checkout the wp/7.1 branch instead of trunk.
git checkout wp/7.1

# Create a new branch for your PR.
git checkout -b my-branch

# Cherry-pick the commit.
git cherry-pick 46048e6380e389508a29f06194ae99e57dbcfb7e

# Check which files have conflicts.
git status

# Resolve the conflict...
# Add the resolved files to the staging area.
git status
git add .
git cherry-pick --continue

# Push the branch to the repository
git push origin my-branch

# Create a PR and set the base to the wp/7.1 branch.
# See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.

[shail-mehta]

@ciampo Thank you for the detailed feedback and suggestions. 🙏

I'm still getting familiar with the ColorPicker internals, so your guidance was very helpful.

[t-hamano]

Removing the Backport to Gutenberg RC label from this PR and adding it to #80435 instead. This is because cherry-picking a manual backport pull request created for wp/7.1 is less likely to cause conflicts than cherry-picking a failed automatic cherry-pick.

[t-hamano]

This PR was manually backported by #80435.