validation.md

wc/store/validation

Table of Contents

• Overview
• Selectors
  • getValidationError
  • getValidationErrorId
  • hasValidationErrors
• Actions
  • clearValidationError
  • clearValidationErrors
  • setValidationErrors
  • hideValidationError
  • showValidationError
  • showAllValidationErrors

Overview

The validation data store provides a way to show errors for fields in the Cart or Checkout blocks.

The data in the store should be a single object, the keys of which are the error IDs and values are the data associated with that error message. The values in the object should contain message and hidden. The message is the error message to display and hidden is a boolean indicating whether the error should be shown or not.

An example of how the data should be structured:

{
    "error-id-1": {
        message: "This is an error message",
        hidden: false,
    },
    "error-id-2": {
        message: "This is another error message",
        hidden: true,
    },
}

When the checkout process begins, it will check if this data store has any entries, and if so, it will stop the checkout process from proceeding. It will also show any errors that are hidden. Setting an error to hidden will not clear it from the data store!

Selectors

getValidationError

Returns the validation error.

Parameters

• errorId string - The error ID to get validation errors for.

Example

const store = select( 'wc/store/validation' );
const billingFirstNameError = store.getValidationError( 'billing-first-name' );

Returns

• object: The validation error which is an object containing message (string) and hidden (boolean).

getValidationErrorId

Gets a validation error ID for use in HTML which can be used as a CSS selector, or to reference an error message. This will return the error ID prefixed with validate-error-, unless the validation error has hidden set to true, or the validation error does not exist in the store.

Parameters

• errorId string - The error ID to get the validation error ID for.

Returns

• string: The validation error ID for use in HTML.

hasValidationErrors

Returns true if validation errors occurred, and false otherwise.

Returns

• boolean: Whether validation errors occurred.

Actions

clearValidationError

Clears a validation error.

Parameters

• errorId string - The error ID to clear validation errors for.

Example

const store = dispatch( 'wc/store/validation' );
store.clearValidationError( 'billing-first-name' );

clearValidationErrors

Clears multiple validation errors at once. If no error IDs are passed, all validation errors will be cleared.

Parameters

• errors string[] | undefined - The error IDs to clear validation errors for. This can be undefined, and if it is, all validation errors will be cleared.

Example

1. This will clear only the validation errors passed in the array.

const store = dispatch( 'wc/store/validation' );
store.clearValidationErrors( [
	'billing-first-name',
	'billing-last-name',
	'terms-and-conditions',
] );

2. This will clear all validation errors.

const store = dispatch( 'wc/store/validation' );
store.clearValidationErrors();

setValidationErrors

Parameters

• errors object: An object containing new validation errors, the keys of the object are the validation error IDs, and the values should be objects containing message (string) and hidden boolean.

Sets the validation errors. The entries in errors will be added to the list of validation errors. Any entries that already exist in the list will be updated with the new values.

Example

const { dispatch } = wp.data;
const { setValidationErrors } = dispatch( 'wc/store/validation' );

setValidationErrors( {
	'billing-first-name': {
		message: 'First name is required.',
		hidden: false,
	},
	'billing-last-name': {
		message: 'Last name is required.',
		hidden: false,
	},
} );

hideValidationError

Hides a validation error by setting the hidden property to true. This will not clear it from the data store!

Parameters

• errorId string: The error ID to hide.

Example

const { dispatch } = wp.data;
const { hideValidationError } = dispatch( 'wc/store/validation' );

hideValidationError( 'billing-first-name' );

showValidationError

Shows a validation error by setting the hidden property to false.

Parameters

• errorId string: The error ID to show.

Example

const { dispatch } = wp.data;
const { showValidationError } = dispatch( 'wc/store/validation' );

showValidationError( 'billing-first-name' );

showAllValidationErrors

Shows all validation errors by setting the hidden property to false.

Example

const { dispatch } = wp.data;
const { showAllValidationErrors } = dispatch( 'wc/store/validation' );

showAllValidationErrors();

---

We're hiring! Come work with us!

🐞 Found a mistake, or have a suggestion? Leave feedback about this document here.