Custom validation

Posts in the developer's cookbook category describe topics that require technical knowledge. Be warned and use the techniques at your own risk. Unless you are an experienced developer, you are strongly advised to ask a professional for support.

Contact Form 7 provides several kinds of user-input validation by default, including:

  • Is a required field filled in?
  • Does an email field have an email address in the correct format?
  • Is an uploaded file in an acceptable file type and size?

You can also add your own custom validation.

To demonstrate how to implement a custom validation, let’s make an email confirmation field. This field prompts you to input the email address that you input in the other field on the form. The two email addresses you’ve input are compared and if they are not identical, a validation error message will be displayed to alert you.

Contact Form 7 doesn’t support email confirmation fields by default (Because I think it’s ridiculous. Who wants to type the same address twice? People know copy and paste). Still, it can be a good example of custom validation.

Validation as a filter

In Contact Form 7, a user-input validation is implemented as a filter function. The filter hook used for the validation varies depending on the type of form-tag and is determined as: wpcf7_validate_ + {type of the form-tag}. So, for text form-tags, the filter hook wpcf7_validate_text is used. Likewise, wpcf7_validate_email* is used for email* form-tags.

Let’s say you have the following email fields in a form:

Email:         [email* your-email]
Confirm email: [email* your-email-confirm]

The following listing shows code that verifies whether the two fields have identical values.

add_filter( 'wpcf7_validate_email*', 'custom_email_confirmation_validation_filter', 20, 2 );
function custom_email_confirmation_validation_filter( $result, $tag ) {
  if ( 'your-email-confirm' == $tag->name ) {
    $your_email = isset( $_POST['your-email'] ) ? trim( $_POST['your-email'] ) : '';
    $your_email_confirm = isset( $_POST['your-email-confirm'] ) ? trim( $_POST['your-email-confirm'] ) : '';
    if ( $your_email != $your_email_confirm ) {
      $result->invalidate( $tag, "Are you sure this is the correct address?" );
  return $result;

Two parameters will be passed to the filter function: $result and $tag. $result is an instance of WPCF7_Validation class that manages a sequence of validation processes. $tag is an instance of WPCF7_FormTag class that appeared in the previous recipes.

Look through the inside of the filter function. First, check the name of the form-tag to ensure the validation is applied only to the specific field (your-email-confirm).

The two email field values are then compared, and if they don’t match, $result->invalidate() will be called. You need to pass two parameters to the invalidate() method: the first parameter should be the $tag variable, and the second parameter is the validation error message that you want the field to display.

Lastly, don’t forget to return the $result.