Integrate hCaptcha

You can add hCaptcha to your HTML Forms very easily. It’s a simple three-step process:

Step #1

Install and activate the hCaptcha plugin, create a free hCaptcha account and add your credentials in the hCaptcha plugin settings.

Step #2

As of version 3.5.0, the hCaptcha plugin offers a direct integration with HTML Forms. Simply go to the Integrations tab of the hCaptcha plugin’s settings, find the HTML Forms box, and select the “Form” toggle like so:

hCaptcha for WordPress Integration

Turning this integration on will automatically add the hCaptcha fields necessary to your forms. You won’t have to do anything else. When viewing your forms in the form editor, the hCaptcha fields can be seen above your submit button.

Step #3

GitHub user despecial recommends this additional code snippet to filter out the hCaptcha fields from your form results:

// Filter hCaptcha fields
function ignored_hf_fields() {
	return array(
		'hcaptcha-widget-id',
		'g-recaptcha-response',
		'h-captcha-response',
		'html_forms_form_nonce',
	);
}
add_filter('hf_ignored_field_names','ignored_hf_fields');

In an upcoming release of HTML Forms, these fields will be removed automatically.


Thank you to hCaptcha for adding support for HTML Forms to their plugin.

Code Snippets

Check out our collection of simple code snippets you can use to get the most out of HTML Forms on your WordPress websites.

Add Class Attribute to Form Tag

add_filter(
	'hf_form_element_class_attr',
	function( $class_attr ) {
		return $class_attr . ' my-class';
	}
);

Add Custom Attribute to Form Tag

add_filter(
	'hf_form_html',
	function( $html ) {
		$html = str_replace( '<form ', '<form ms-signup="true" ', $html );
		return $html;
	}
);

Add Custom Form Action

use HTML_Forms\Actions\Action;
use HTML_Forms\Form;
use HTML_Forms\Submission;

class MyCustomAction extends Action {

	public $type  = 'pushbullet';
	public $label = '';

	public function __construct() {
		$this->label = __( 'Send to Pushbullet', 'html-forms' );
	}

	/**
	 * @return array
	 */
	private function get_default_settings() {
		return array(
			'url' => '',
		);
	}

	/**
	 * @param array $settings
	 * @param string|int $index
	 */
	public function page_settings( $settings, $index ) {
		$settings = array_merge( $this->get_default_settings(), $settings );
		?>
		<span class="hf-action-summary"><?php printf( 'Pushbullet' ); ?></span>
		<input type="hidden" name="form[settings][actions][<?php echo $index; ?>][type]" value="<?php echo $this->type; ?>" />
		<table class="form-table">
			<tr>
				<th><label><?php echo __( 'Pushbullet API URL', 'html-forms' ); ?> <span class="hf-required">*</span></label></th>
				<td>
					<input name="form[settings][actions][<?php echo $index; ?>][url]" value="<?php echo esc_attr( $settings['url'] ); ?>" type="text" class="regular-text" placeholder="http://...." required />
				</td>
			</tr>
		</table>
		<?php
	}

	/**
	 * Processes this action
	 *
	 * @param array $settings
	 * @param Submission $submission
	 * @param Form $form
	 */
	public function process( array $settings, Submission $submission, Form $form ) {
		// TODO: Send HTTP request to PushBullet API URL: $settings['url']
	}
}

$my_custom_action = new MyCustomAction();
$my_custom_action->hook();

Add HTML to Form Dynamically

add_filter(
	'hf_form_markup',
	function( $markup ) {
		$markup .= '<input type="hidden" name="HIDDEN_FIELD" value="My value" />';
		return $markup;
	}
);

HTML forms will check the number of configured fields versus the number of submitted fields, and ignore the submission if it’s mismatching. For that reason, if you like to dynamically add more than 1 field dynamically, you need to disable the field counter with the following filter:

add_filter( 'hf_validate_form_request_size', '__return_false' );

Add Tag to Mailchimp Contact

This requires the MC4WP plugin to be active and configured.

Give users a link to a form, and include “?hfmuc_email={{their_email}}” as a querystring parameter.

Then make sure the form has a hidden field named “EMAIL” whose value is “{{hfmuc_email}}” like this example:

<input type="hidden" name="EMAIL" placeholder="Your email" required value="{{hfmuc_email}}" />

Find your list ID and put it in $list_id below. Then local the HTML Forms slug (seen when editing the form) and put it in $form_slug. Next, add any tags you want to $tags_data.

Now the user will get a link to the form, fill it out (no need to re-enter their email), and upon successful submission, those tags will be added to their Mailchimp contact.

use \HTML_Forms\Submission;
use HTML_Forms\Form;

// Get the user's email from the query parameters
add_filter(
	'hf_form_html',
	function ( $html ) {
		$email = isset( $_GET['hfmuc_email'] ) ? $_GET['hfmuc_email'] : '';
		return str_replace( '{{hfmuc_email}}', $email, $html );
	}
);
// Adds tags to the given user.
add_action(
	'hf_form_success',
	function ( $submission, $form ) {
		// Check that it's the right form.
		$form_slug = 'survey-1';
		if ( $form->slug !== $form_slug ) {
			return;
		}

		$email_address = $submission->data['EMAIL'];
		$api           = mc4wp_get_api_v3();

		// aka "audience ID". See https://mailchimp.com/help/find-audience-id/
		$list_id = '32ccd044c3';

		// see https://mailchimp.com/developer/reference/lists/list-members/list-member-tags/#read-get_lists_list_id_members_subscriber_hash_tags
		$tags_data = array(
			'tags' => array(
				array(
					'name'   => 'Test',
					'status' => 'active',
				),
			),
		);

		$result = $api->update_list_member_tags(
			$list_id,
			$email_address,
			$tags_data
		);
	},
	10,
	2
);

Add URL to Email Message

It’s possible to filter the email action message with PHP. This example will add the URL the form was submitted from to the end of the email notification message.

add_filter(
	'hf_action_email_message',
	function ( $message ) {
		return $message . sprintf( '<br />Referrer URL: %s', esc_html( $_SERVER['REQUEST_URI'] ) );
	}
);

Custom Form Message

The default message keys are:

  • success
  • invalid_email
  • required_field_missing
  • error
add_filter(
	'hf_form_message_success',
	function( $message ) {
		return 'Your custom success message here';
	}
);

Custom Form Validation

// validate form request (all forms)
// this will validate that the field with name "BEST_VEGETABLE" is set and has a value of "carrot"
add_filter(
	'hf_validate_form',
	function( $error_code, $form, $data ) {
		if ( ! isset( $data['BEST_VEGETABLE'] ) || $data['BEST_VEGETABLE'] !== 'carrot' ) {
			$error_code = 'wrong_answer';
		}

		return $error_code;
	},
	10,
	3
);

// validate form request (form with ID 60 only)
add_filter(
	'hf_validate_form',
	function( $error_code, $form, $data ) {
		if ( $form->ID != 60 ) {
			return $error_code;
		}

		if ( ! isset( $data['BEST_VEGETABLE'] ) || $data['BEST_VEGETABLE'] !== 'carrot' ) {
			$error_code = 'wrong_answer';
		}

		return $error_code;
	},
	10,
	3
);

// register error message for our custom error code
add_filter(
	'hf_form_message_wrong_answer',
	function( $message ) {
		return 'Sorry, but the best vegetable is a carrot!';
	}
);

Do Not Store IP Address and User Agent

add_action(
	'hf_process_form',
	function( $form, $submission ) {
		$submission->ip_address = '';
		$submission->user_agent = '';
	},
	10,
	2
);

File Upload Direct Links

Instruct HTML Forms to not link to WP Media attachments for uploaded files, but use a direct link to the actual file. This requires the HTML Forms Premium add-on.

add_filter( 'hf_file_upload_use_direct_links', '__return_true' );

Disable File Uploads to WordPress Admin Media Library

This requires the HTML Forms Premium add-on.

add_filter( 'hf_upload_add_to_media', '__return_false' );

Change Maximum Size Allowed for File Uploads

This requires the HTML Forms Premium add-on.

add_filter(
	'hf_upload_max_filesize',
	function( $size ) {
		// size in bytes, 1000000 = 1MB
		return 1000000;
	}
);

Filter Email Action to Specific Email Address

add_filter(
	'hf_action_email_to',
	function( $to, $submission ) {
		if ( $submission->data['FOO'] === 'BAR' ) {
			return 'support@acmeinc.com';
		}

		return $to; // default "To" as specified in action settings
	},
	10,
	2
);

Manually Load HTML Forms JavaScript

If you’re having issues with the HTML Forms JavaScript file not being loaded, you can use the following snippet to load it manually.

add_action(
	'wp_enqueue_scripts',
	function() {
		wp_enqueue_script( 'html-forms' );
	},
	90
);

Modify Email Action Recipient

add_action(
	'hf_action_email_to',
	function ( $to, \HTML_Forms\Submission $submission ) {
		// $to contains the default recipient, from the action settings
		// you can replace it with a different email addresses or turn it into an array of recipients
		return array( $to, 'john.doe@email.com' );
	}
);

Create a Multi-Step Form

<!-- Step 1 -->
<div data-show-if="_STEP:">
  <p>
      <label>Name</label>
      <input type="text" name="NAME" placeholder="" value="Danny" required />
  </p>
  <p>
    <button type="button" name="_STEP" value="2">Continue to step 2</button>
  </p>
</div>

<!-- Step 2 -->
<div data-show-if="_STEP:2">
  <p>
      <label>Email address</label>
      <input type="email" name="EMAIL" placeholder="Your email address" value="danny@email.com" required />
  </p>

  <p>
      <button type="button" name="_STEP" value="3">Continue to step 3</button>
      <button type="button" name="_STEP" value="">Back</button>
  </p>
</div>

<!-- Step 3 -->
<div data-show-if="_STEP:3">
  <p>
      <input type="submit" value="Send" />
  </p>
</div>

Perform Action After Successful Form Submission

This code runs for every successful form submission.

add_action(
	'hf_form_success',
	function( $submission, $form ) {
		// You can do stuff here.
		// $form contains details about the submitted form
		// $submission contains details about the submission, like the form data.
	},
	10,
	2
);

Template Tags

This example replaces {{replace_me}} with “replaced!” using a simple string replacement.

add_filter(
	'hf_template_tags',
	function( $tags ) {
		$tags['replace_me'] = 'replaced!';
		return $tags;
	}
);

This example uses a function accepting a single parameter to determine the replacement value

Example: {{replace_me.foo}}

add_filter(
	'hf_template_tags',
	function( $tags ) {
		$tags['replace_me'] = function( $key ) {
			if ( $key === 'foo' ) {
				return 'bar';
			}

			return 'not bar';
		};
		return $tags;
	}
);

Filter Hooks

It’s possible to modify or extend the default behavior of HTML Forms beyond what is possible with the available settings. To achieve this, you can use any of the available action hooks and filter hooks in the plugin.

To learn more about what filter hooks are, please refer to the WordPress plugin API documentation.

Available Filter Hooks

Below is a list of all available filter hooks in the plugin.

hf_form_element_action_attr

Filters the action attribute for the form element.

Default value: null

hf_form_element_class_attr

Filters the CSS classes which are added to the form element’s class attribute.

Default value: ""

hf_form_html

Filters the complete form HTML when the form is outputted.

hf_validate_form

Filters the error code when a form is validated. Return an empty string if the form validates without errors.

Default value: ""

Conditional Elements

Conditional elements are supported in HTML Forms by using two special attributes: data-show-if and data-hide-if.

Using these attributes allows you to hide or show parts of your form by referencing the name attribute of a field in your form.

For example, you could choose to only show the submit button after the email field is filled.

<input type="email" name="EMAIL" required />
<input type="submit" value="Send" data-show-if="EMAIL" />

Let’s do another example where you have a help text is hidden after someone starts typing in the field it describes.

<input type="text" name="NAME" />
<p data-hide-if="NAME">Enter your name in the field above.</p>

Specifying an Exact Value

The examples above will show or hide an element whenever the field that it is depending on contains any value, regardless of the actual value.

Sometimes you want to depend on an exact value though. This can be done by following the field name with a colon and the value you need, like this: NAME:VALUE.

Let’s build a form with a list of checkboxes, where a message shows up only when one particular choice is selected.

<input type="checkbox" name="JOB" value="Marketeer" /> Marketeer
<input type="checkbox" name="JOB" value="Developer" /> Developer
<input type="checkbox" name="JOB" value="Recruiter" /> Recruiter

<div data-show-if="JOB:Recruiter">
    Hi, recruiter!
</div>

Specifying Multiple Values

Continuing with the above example, what if you wanted to show part of your form for both developers and marketeers?

You can specify multiple expected values by separating them with a |.

<input type="checkbox" name="JOB" value="Marketeer" /> Marketeer
<input type="checkbox" name="JOB" value="Developer" /> Developer
<input type="checkbox" name="JOB" value="Recruiter" /> Recruiter

<div data-show-if="JOB:Marketeer|Developer">
    Hi, marketeer or developer!
</div>

JavaScript Events

HTML Forms fires several JavaScript events when visitors interact with a form on your site. You can hook into these events to run your own code, for example to send events to Google Analytics.

Available Events

The following events are available:

submit

Fires right after the form is submitted, but before the request is processed.

submitted

Fires after the request is processed, for both successful submissions and errors.

error

Fires after the request is processed when a validation error occurs, for example, when a required field is missing.

success

Fires after the request is processed, and the submission was a success.

Hooking Into an Event

The following code example hooks into the “success” event for all forms (see above).

<script>
html_forms.on('success', function(formElement) {
   // your code goes here
});
</script>

Alternatively, you can hook into a specific form using the default browser events API too.

<script>
document.querySelector('.hf-form-5').on('hf-success', function(e) {
   // your code goes here
});
</script>

You can add this code directly to your form mark-up or to any other JavaScript file that is loaded on your site.

Custom Form Validation

HTML Forms will perform the following form validation by itself:

  • All input fields marked as required should have a non-empty value.
  • All fields of type “email” should have a value that looks like an email address, or no value at all (if not required).

If you want to perform additional form validation, then you can do so by hooking into the hf_validate_form filter hook.

The following example will only accept the form submission if the field named “BEST_VEGETABLE” is filled and the value “carrot” is submitted.

add_filter( 'hf_validate_form', function( $error_code, $form, $data ) {
	if( ! isset($data['BEST_VEGETABLE']) || $data['BEST_VEGETABLE'] !== 'carrot' ) {
		$error_code = 'wrong_answer'; 
	}

	return $error_code;
}, 10, 3 );

Showing a Custom Error Message

The $error_code indicates what message should be shown to the person filling out the form. Since we did not register a message with that error code, the plugin will default to showing the general error message instead.

Let’s improve upon this by showing a more detailed error message describing exactly why the form validation failed.

add_filter( 'hf_form_message_wrong_answer', function( $message ) {
    return 'Sorry, but the best vegetable is a carrot!';
});

Action Hooks

It’s possible to modify or extend the default behavior of HTML Forms beyond what is possible with the available settings. To achieve this, you can use any of the available action hooks and filter hooks in the plugin.

To learn more about what action hooks are, please refer to the WordPress plugin API documentation.

Available Action Hooks

Below is a list of all available action hooks in the plugin.

hf_form_success

Runs when a form is submitted successfully, after the submission was saved.

Parameters: $submission$form

hf_form_error

Runs when a form is submitted but a validation error occurs.

Parameters: $error_code$form$data

Sending E-mail Notifications

You can configure HTML Forms to send out an email notification whenever a form is successfully submitted.

To set this up, edit your form and open up the Actions tab. Near the bottom of the page should be a heading titled Add Form Action with a Send Email button.

Clicking that Send Email button will add a settings block to the page that should look like this:

Send Email action found in the HTML Forms WordPress plugin.

Settings

Here’s what each setting does.

From

Define the email address you wish the message to come from. This field accepts field value placeholders.

It is advised to pick an address with the same domain name as your website to prevent ending up in someone’s SPAM folder. For example, if your website is flowers.com, then lee@flowers.com is better than leeflowers@gmail.com.

Also note that if you use a third-party email senders on your WordPress site that the address in this field must be validated with that service.

To

The email address that the email should be sent to. This field also accepts field value placeholders.

Subject

The subject of your email message. This field also accepts field value placeholders.

Message

The actual message body of the email. This field also accepts field value placeholders.

Content Type

You can decide if your email is HTML or plain text.

Additional Headers

You can include custom headers with your email. We recommend, if you want to define a Reply-To address, you use this setting with placeholders.

Redirect to URL After Form Submit

You can configure HTML Forms to redirect to a certain page on your website after each successful form submission. An example use case would be to send visitors to a “Thank You” page after they submit your form.

To set this up, open up your form, navigate to the Settings tab and locate the setting for a redirect:

Redirect to URL feature found in the HTML Forms WordPress plugin.

Make sure to use complete (absolute) URL’s and to redirect to a page that describes that the form was processed successfully. You don’t want to confuse your visitors with a random redirect.

Template Variables

HTML Forms provides several template variables you can use in your form content. These form variables will be dynamically replaced when the form is shown. Currently, you can use the following variables.

user

Will be replaced with the specified property of the currently logged-in user.

{{ user.user_email }}

url_params

This will be replaced with a parameter from the page URL, or with an empty string if the specified URL parameter does not exist.

{{url_params.utm_source}}

post

This will be substituted with the specified property of the post that is viewed on the page the form is displayed on.

{{post.ID}}