useFormValidity returns validity and isValid

WordPress · oandregal · Oct 16, 2025 · Aug 29, 2025 · Oct 15, 2025 · Oct 15, 2025
commit 522dd496439869211bc8721c3247ef68c740cd2c
@@ -726,7 +726,10 @@ Parameters:
 -   `fields`: the fields config, as described in the "fields" property of DataViews.
 -   `form`: the form config, as described in the "form" property of DataViews.
 
-Returns an object containing the errors. Each property is a field ID, containing a description of each error type. For example:
+Returns an object containing:
+
+-   `isValid`: a boolean indicating if the form is valid.
+-   `validity`: an object containing the errors. Each property is a field ID, containing a description of each error type. For example:
 
 ```js
 {
@@ -740,8 +743,8 @@ Returns an object containing the errors. Each property is a field ID, containing
 			message: 'Value must be one of the elements.' // Optional
 		},
 		custom: {
-			type: 'invalid',
-			message: 'Custom message'
+			type: 'validating',
+			message: 'Validating...'
 		}
 	}
 }

diff --git a/packages/dataviews/src/hooks/test/use-form-validity.ts b/packages/dataviews/src/hooks/test/use-form-validity.ts
@@ -23,10 +23,13 @@ describe( 'useFormValidity', () => {
 			},
 		];
 		const form = { fields: [ 'valid_order' ] };
-		const { result } = renderHook( () =>
-			useFormValidity( item, fields, form )
-		);
-		expect( result.current ).toEqual( undefined );
+		const {
+			result: {
+				current: { validity, isValid },
+			},
+		} = renderHook( () => useFormValidity( item, fields, form ) );
+		expect( validity ).toEqual( undefined );
+		expect( isValid ).toBe( true );
 	} );
 
 	it( 'fields can override the defaults', () => {
@@ -46,10 +49,13 @@ describe( 'useFormValidity', () => {
 			},
 		];
 		const form = { fields: [ 'order' ] };
-		const { result } = renderHook( () =>
-			useFormValidity( item, fields, form )
-		);
-		expect( result.current ).toEqual( undefined );
+		const {
+			result: {
+				current: { validity, isValid },
+			},
+		} = renderHook( () => useFormValidity( item, fields, form ) );
+		expect( validity ).toEqual( undefined );
+		expect( isValid ).toBe( true );
 	} );
 
 	describe( 'isValid.required', () => {
@@ -68,10 +74,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'tags' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.tags ).toEqual( REQUIRED_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( REQUIRED_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'array is invalid when required but not an array', () => {
@@ -86,10 +95,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'tags' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.tags ).toEqual( REQUIRED_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( REQUIRED_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'array is valid when required and has values', () => {
@@ -104,10 +116,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'tags' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current ).toEqual( undefined );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
 		} );
 	} );
 
@@ -130,10 +145,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'author' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.author ).toEqual( ELEMENTS_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.author ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'text is valid when value is one of the elements', () => {
@@ -152,10 +170,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'status' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current ).toEqual( undefined );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
 		} );
 
 		it( 'text is invalid when value is not one of the elements', () => {
@@ -174,10 +195,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'status' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.status ).toEqual( ELEMENTS_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.status ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'integer is valid when value is one of the elements', () => {
@@ -197,10 +221,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'priority' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current ).toEqual( undefined );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
 		} );
 
 		it( 'integer is invalid when value is not one of the elements', () => {
@@ -220,10 +247,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'priority' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.priority ).toEqual( ELEMENTS_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.priority ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'number is invalid if value is not one of the elements', () => {
@@ -239,10 +269,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'price' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.price ).toEqual( ELEMENTS_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.price ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'array is valid if all items are part of the elements', () => {
@@ -259,10 +292,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'tags' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current ).toEqual( undefined );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
 		} );
 
 		it( 'array is invalid when not all items are part of the elements', () => {
@@ -279,10 +315,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'tags' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.tags ).toEqual( ELEMENTS_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'array is invalid when value is not an array', () => {
@@ -301,10 +340,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'tags' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.tags ).toEqual( ELEMENTS_MESSAGE );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
 		} );
 	} );
 
@@ -318,10 +360,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'order' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current ).toEqual( undefined );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
 		} );
 
 		it( 'integer is invalid if value is not integer when not empty', () => {
@@ -333,15 +378,18 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'order' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.order ).toEqual( {
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.order ).toEqual( {
 				custom: {
 					type: 'invalid',
 					message: 'Value must be an integer.',
 				},
 			} );
+			expect( isValid ).toBe( false );
 		} );
 
 		it( 'number is valid if value is finite', () => {
@@ -353,10 +401,13 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'price' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current ).toEqual( undefined );
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
 		} );
 
 		it( 'number is invalid if value is not finite when not empty', () => {
@@ -368,15 +419,18 @@ describe( 'useFormValidity', () => {
 				},
 			];
 			const form = { fields: [ 'price' ] };
-			const { result } = renderHook( () =>
-				useFormValidity( item, fields, form )
-			);
-			expect( result.current?.price ).toEqual( {
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.price ).toEqual( {
 				custom: {
 					type: 'invalid',
 					message: 'Value must be a number.',
 				},
 			} );
+			expect( isValid ).toBe( false );
 		} );
 	} );
 } );
@@ -58,7 +58,7 @@ export function useFormValidity< Item >(
 	item: Item,
 	fields: Field< Item >[],
 	form: Form
-): FormValidity {
+): { validity: FormValidity; isValid: boolean } {
 	const [ formValidity, setFormValidity ] = useState< FormValidity >();
 
 	const previousValidatedValuesRef = useRef< Record< string, any > >( {} );
@@ -287,7 +287,16 @@ export function useFormValidity< Item >(
 		validate();
 	}, [ validate ] );
 
-	return formValidity;
+	return {
+		validity: formValidity,
+		isValid:
+			! formValidity ||
+			Object.values( formValidity ).every( ( fieldValidation ) =>
+				Object.values( fieldValidation ).every(
+					( validation ) => validation.type === 'valid'
+				)
+			),
+	};
 }
 
 export default useFormValidity;