Form components: Support async validation (#71184)

* Form components: Support async validation

* Move demo to Overview doc

* Improve support for multiple errors

* Update "Overview" stories

* Rename `customValidator` prop

* Switch to spinner

* Update usage in DataForm

* Add changelog

* Always prioritize error message over status

* Only show `validating` state after 1s elapses

* Extract validation indicator to separate file

* Simplify

* Add guidance for status indicators

* Rename CSS classes

* Rename indicator

* Try spinning icon

* Rename `customValidityMessage`

* Make `message` required

An icon is not enough to communicate the status

* Remove unnecessary optional

* Revert "Try spinning icon"

This reverts commit 88ab560.

Author: mirka

packages/components/CHANGELOG.md

@@ -6,6 +6,10 @@
 
 -   Upgrade `gradient-parser` to version `1.1.1` to support HSL/HSLA color, CSS variables, and `calc()` expressions ([#71186](https://github.com/WordPress/gutenberg/pull/71186)).
 
+### Internal
+
+-   Validated form controls: Add support for async validation. This is a breaking API change that splits the `customValidator` prop into an `onValidate` callback and a `customValidity` object. ([#71184](https://github.com/WordPress/gutenberg/pull/71184)).
+
 ## 30.1.0 (2025-08-07)
 
 ### Enhancement

packages/components/src/validated-form-controls/components/checkbox-control.tsx

@@ -17,7 +17,8 @@ type Value = CheckboxControlProps[ 'checked' ];
 const UnforwardedValidatedCheckboxControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -37,9 +38,10 @@ const UnforwardedValidatedCheckboxControl = (
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			ref={ mergedRefs }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
 					'input[type="checkbox"]'

packages/components/src/validated-form-controls/components/combobox-control.tsx

@@ -17,7 +17,8 @@ type Value = ComboboxControlProps[ 'value' ];
 const UnforwardedValidatedComboboxControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -50,9 +51,10 @@ const UnforwardedValidatedComboboxControl = (
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			ref={ mergedRefs }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
 					'input[role="combobox"]'

packages/components/src/validated-form-controls/components/custom-select-control.tsx

@@ -21,7 +21,8 @@ type Value = CustomSelectControlProps[ 'value' ];
 const UnforwardedValidatedCustomSelectControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -43,9 +44,10 @@ const UnforwardedValidatedCustomSelectControl = (
 			<ControlWithError
 				required={ required }
 				markWhenOptional={ markWhenOptional }
-				customValidator={ () => {
-					return customValidator?.( valueRef.current );
+				onValidate={ () => {
+					return onValidate?.( valueRef.current );
 				} }
+				customValidity={ customValidity }
 				getValidityTarget={ () => validityTargetRef.current }
 			>
 				<CustomSelectControl

packages/components/src/validated-form-controls/components/input-control.tsx

@@ -17,7 +17,8 @@ type Value = InputControlProps[ 'value' ];
 const UnforwardedValidatedInputControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedInputControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<InputControl

packages/components/src/validated-form-controls/components/number-control.tsx

@@ -17,7 +17,8 @@ type Value = NumberControlProps[ 'value' ];
 const UnforwardedValidatedNumberControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedNumberControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<NumberControl

packages/components/src/validated-form-controls/components/radio-control.tsx

@@ -17,7 +17,8 @@ type Value = RadioControlProps[ 'selected' ];
 const UnforwardedValidatedRadioControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -35,9 +36,10 @@ const UnforwardedValidatedRadioControl = (
 			markWhenOptional={ markWhenOptional }
 			// TODO: Upstream limitation - RadioControl does not accept a ref.
 			ref={ mergedRefs }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
 					'input[type="radio"]'

packages/components/src/validated-form-controls/components/range-control.tsx

@@ -17,7 +17,8 @@ type Value = RangeControlProps[ 'value' ];
 const UnforwardedValidatedRangeControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedRangeControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<RangeControl

packages/components/src/validated-form-controls/components/select-control.tsx

@@ -26,7 +26,8 @@ type Value = SelectControlProps[ 'value' ];
 const UnforwardedValidatedSelectControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -51,9 +52,10 @@ const UnforwardedValidatedSelectControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<SelectControl

packages/components/src/validated-form-controls/components/stories/checkbox-control.story.tsx

@@ -32,6 +32,12 @@ export default meta;
 export const Default: StoryObj< typeof ValidatedCheckboxControl > = {
 	render: function Template( { onChange, ...args } ) {
 		const [ checked, setChecked ] = useState( false );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedCheckboxControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedCheckboxControl
@@ -41,6 +47,17 @@ export const Default: StoryObj< typeof ValidatedCheckboxControl > = {
 					setChecked( value );
 					onChange?.( value );
 				} }
+				onValidate={ ( value ) => {
+					if ( value ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'This checkbox may not be checked.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -49,10 +66,4 @@ Default.args = {
 	required: true,
 	label: 'Checkbox',
 	help: 'This checkbox may neither be checked nor unchecked.',
-	customValidator: ( value ) => {
-		if ( value ) {
-			return 'This checkbox may not be checked.';
-		}
-		return undefined;
-	},
 };