Form status

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.

Each contact form instance rendered on the frontend has a status. The status must be one of the predefined statuses or a user-defined custom status that starts with the custom- prefix, and transitions from one to another according to user interaction.

Predefined statuses and meanings

  • init — The initial status.
  • invalid — Form submission aborted because there were invalid user inputs.
  • unaccepted — Form submission aborted because the user didn’t accept some conditions.
  • spam — Form submission aborted because spam activity was detected.
  • aborted — Form submission aborted.
  • sent — Form submission completed, and email was sent successfully.
  • failed — Form submission completed, but email failed to be sent.
  • submitting — Form submission is in process.
  • resetting — Form resetting is in process.
  • validating — Frontend form validation is in process.
  • payment-required — Form submission half completed, and payment by the user is now required.

Class for status

The form element has an HTML class that represents the current status. You can use this class in a CSS selector to make a style rule which is active only when the form has a specific status. As an example, see the following style rules (cited from Contact Form 7’s frontend stylesheet):

.wpcf7 form .wpcf7-response-output {
	margin: 2em 0.5em 1em;
	padding: 0.2em 1em;
	border: 2px solid #00a0d2; /* Blue */

.wpcf7 form.init .wpcf7-response-output,
.wpcf7 form.resetting .wpcf7-response-output,
.wpcf7 form.submitting .wpcf7-response-output {
	display: none;

.wpcf7 form.sent .wpcf7-response-output {
	border-color: #46b450; /* Green */

.wpcf7 form.failed .wpcf7-response-output,
.wpcf7 form.aborted .wpcf7-response-output {
	border-color: #dc3232; /* Red */

.wpcf7 form.spam .wpcf7-response-output {
	border-color: #f56e28; /* Orange */

.wpcf7 form.invalid .wpcf7-response-output,
.wpcf7 form.unaccepted .wpcf7-response-output,
.wpcf7 form.payment-required .wpcf7-response-output {
	border-color: #ffb900; /* Yellow */

DOM event on status change

When the status of a contact form changes, Contact Form 7 triggers the custom DOM event wpcf7statuschanged. In addition to the basic properties, an event object of wpcf7statuschanged has the properties detail.status and detail.prevStatus, representing the current status and previous status respectively. See the following coding example:

document.addEventListener( 'wpcf7statuschanged', function( event ) {
	console.log( `Status transitioned from ${ event.detail.prevStatus } to ${ event.detail.status }.` );
}, false );

The inert-on-(status) classes

Contact Form 7 supports the functionality of the inert-on-(status) HTML classes. The (status) part is a variable which is filled by a status name. When the status changes and the wpcf7statuschanged DOM event fires, Contact Form 7’s frontend script will set the inert attribute on elements that have the inert-on-(the new status) class. Therefore, when the form status changes to sent, for example, the elements with the inert-on-sent class will become inert.