Basic

Form

Label

This is the label (title) of your form. As well as entering a label into this field, you can also edit the label at the top of the page. You should enter an easy-to-understand label for your form, for example, Contact Us or Appointment Request. This label is used to identify your form in WordPress and can also be added to the top of your form for website visitors to see using the Show Label setting.

Show Label

If enabled the label will be shown at the top of your form for website visitors to see. If you do not want the label to appear, uncheck this box.

Enable Form Submit On Enter

Allow the form to be submitted if someone types Enter/Return. Not advised for e-commerce forms.

Lock Save & Submit Buttons

A common issue with forms is that sometimes website visitors will double click a submit button. On a conventional form, this can often cause duplicate submissions to be processed.

WS Form comes with built-in duplicate protection. When this setting is enabled, it will disable the save & submit buttons once they have been clicked to prevent duplication from happening. We recommend leaving this setting enabled.

Unlock Save & Submit Buttons

When this setting is enabled, it will enable the save & submit buttons once the form has been successfully submitted or saved. It will also enable the button if a form error occurs. We recommend leaving this setting enabled.

Reset Form After Submit

When enabled WS Form will reset the form after it is successfully submitted so that any data in the fields is removed. We recommend keeping this setting enabled.

An example of when you would want to disable this setting might be if someone is doing repeated data entry into a form and only changing part of the submission each time.

Custom Form Action

If you do not want WS Form to process your form, enter a custom form action URL to post the form data to in this setting. WS Form will still perform client side validation before posting the data to the URL you have entered. Actions will not fire if a custom form action is entered.

If you do not have a custom form endpoint, leave this field blank.

Tabs

Remember Last Tab Clicked

If enabled WS Form will store the last tab a website visitor has clicked in a cookie on their browser. This makes navigating a complex form easier if they return to the form at a later date to complete it. This is particularly helpful if you have added a Save button to a form, which will save the current form so that it can be retrieved later.

Tab Validation

Tab validation prevents users from progressing to the next tab unless the current tab is validated. Check this setting to enable this feature.

Show Invalid Fields

If a tab contains invalid fields and the user attempts to progress to the next tab, WS Form will show invalid feedback. If you have the Focus Invalid Fields setting enabled (See below) it will also focus on the first field that is invalid.

Hide Tabs

Check this setting to hide the tabs but retain tab functionality (e.g. Next Tab button).

Fields

Invalid Feedback Text

If a required field is empty when the form is validated, invalid feedback text will shown.

The default invalid feedback text is: This field is required.

You can change the invalid feedback by changing this setting. You can also override invalid feedback text at a field level too.

The following WS Form variables can be used in this setting:

Variable	Description
#label	The field label.
#label_lowercase	The field label lowercase.

Focus Invalid Fields

If this setting is enabled, WS Form will focus on the first invalid field it finds when a form is submitted. This is a convenience feature that makes it easier for a website visitor to locate issues within their data entry.

Errors

Show Server Side Error Messages

Shows error messages if a server side error occurs when a form is submitted.

Type

There are five different types of error message:

• Success (Green)
• Information (Blue)
• Warning (Orange)
• Danger (Red)
• None

Position

You can choose to position error messages to show before or after your form. For large forms we would recommend enabling Scroll To Top if you choose before positioning, so that the message is seen by the user.

Clear Other Messages

If enabled any other messages on the screen will be cleared first.

Scroll To Top

If enabled the browser will scroll to the top of the page when the error message is shown. Choose from None, Instant, or Smooth.

Scroll Offset (Pixels)

Number of pixels to offset the final scroll position by. Useful for sticky headers. For example, if your header is 100 pixels tall, enter 100 into this setting. This setting appears if Scroll To Top is set to Instant or Smooth.

Scroll Duration (ms)

Duration of the smooth scroll in milliseconds. This setting appears if Scroll To Top is set to Smooth.

Hide Form When Shown

If enabled the form will be hidden when the error message is shown.

Show Duration (ms)

Use this field to enter how long the error message is shown before the next action fires. The value entered should be in milliseconds (1 second = 1000 milliseconds). If you enter a value in this field, the following two options are also available.

Hide Message After Duration

If enabled the error message will be hidden after the Show Duration (ms) has elapsed.

Show Form After Duration

If enabled the form will be shown after the Show Duration (ms) has elapsed. This setting appears if Hide Form When Shown is enabled.

Styling

Form

Style

Choose which style to use for this form. This setting appears when the WS Form styler is enabled. Learn more about the styler.

Breakpoint Queries

Choose whether column breakpoints respond to the browser width or the form width. This setting appears when using the WS Form framework.

• Browser Width (@media) — Breakpoints respond to the browser / viewport width.
• Form Width (@container) — Breakpoints respond to the form width. Useful for forms in sidebars, modals, or other narrow containers.

Fields

Default Label Position

When WS Form is installed, labels are positioned at the top of a field. You can change this setting to set label positioning to be one of the following options:

• Top
• Left
• Right
• Bottom

Note that some frameworks do not support all of these label positions.

Changing this setting will affect all fields that have their label position set to Default.

Default Label Width (Columns)

If the label position of a field is set to left or right, you can specify how wide the label will be. You can consider the overall width of the label and the field to be 12 columns. By default labels are rendered at 3 columns wide (1/4 width), which means the field itself is 9 columns wide (3/4 width). You can change the width of the label using this setting.

Default Help Position

When WS Form is installed, help text is positioned below each field. You can change this setting to set the help positioning to be one of the following options:

• Top
• Bottom

Changing this setting will affect all fields that have their help position set to Default.

Required Fields

Show Required HTML

When this is enabled, WS Form will output a small Required caption next to the label of any fields that are set as Required. If this is disabled, the captions will not be rendered.

Custom Required HTML

You can change the Required caption to anything you wish using this setting.

For example you could change it to: <small>Required</small>

Classes

Form Wrapper

To add a class to the actual form element itself, enter a class (or classes) to this setting. To add multiple classes, add a space between the class names.

Tabs Wrapper

To add a class to the tabs wrapper, enter a class (or classes) to this setting. To add multiple classes, add a space between the class names.

Tab Content Wrapper

To add a class to the content wrapper of all tabs, enter a class (or classes) to this setting. To add multiple classes, add a space between the class names.

Section Wrapper

To add a class to all sections, enter a class (or classes) to this setting. To add multiple classes, add a space between the class names.

Field Wrapper

To add a class to all field wrappers, enter a class (or classes) to this setting. To add multiple classes, add a space between the class names.

Field

To add a class to all fields, enter a class (or classes) to this setting. To add multiple classes, add a space between the class names.

Heading HTML Masks

Form

If you have enabled label rendering (see above), then the label will be shown at the top of the form. For developers this will be rendered in an h2 wrapper. You can override this by entering a different mask into this field. Use #label where you want the label to be added.

For example you could change this to: <h3>#label</h3>

Tab

If you have enabled label rendering of a tab, then the label will be shown at the top of each tab. For developers this will be rendered in an h3 wrapper. You can override this by entering a different mask into this field. Use #label where you want the label to be added.

For example you could change this to: <h4>#label</h4>

Section

If you have enabled label rendering of a section, then the label will be shown at the top of each section. For developers this will be rendered in a legend wrapper. A legend is used because this label is added within a fieldset. You can override this by entering a different mask into this field. Use #label where you want the label to be added.

For example you could change this to: <legend><em>#label</em></legend>

Populate

The Populate tab will appear if you have any actions that provide support for this feature. Auto populate pulls data from an external source and makes that data available for setting the default value of fields.

Populate Using Action

Enable

If checked, WS Form will populate the form with data from an action.

To use this feature, check Enable, then select the action you want to pull data from. Follow the on-screen prompts for setting up populate mapping and then click the Save button at the bottom.

Learn more about populating forms.

Spam Protection

Forms created by WS Form are inherently less likely to be prone to spam. This is because they are generated on the fly in a website visitor’s browser when a page loads and are often not even seen by spam bots. In addition to this, we offer a variety of additional spam protection measures.

To read more about preventing spam, click here.

IP Throttling

The IP Throttling setting allow you to only allow submissions from an IP address to be submitted one or more times. In order to use this feature your form will need:

• Remote IP Address tracking enabled. Learn more about form tracking.
• A Save Submission action.

Enable

When checked, limit by IP submission count will be enabled.

Maximum Count

This defines the maximum number of submissions that will be accepted from the same IP address for the given Duration setting.

Duration

This setting is used in conjunction with the Maximum Count setting to determine how many submissions will be accepted from the same IP address.

Limit Reached Message

The message to show if the limit is reached. Leave blank if you want nothing to show.

Message Style

You can wrap the message in a styled box, or you can select None to output the message as is.

IP Blocklist

The IP Blocklist setting allows you to specify IP addresses you want to block for this form. In order to use this feature your form will need Remote IP Address tracking enabled.

Enable

When checked, limit by IP blocklist will be enabled.

IP Addresses

To add an IP address to block:

1. Click the Add icon.
2. Enter an IPv4 or IPv6 address.
3. Repeat this for each IP address you want to add.

You can also bulk specify IP address by using the wsf_submit_limit_ips WordPress filter hook.

Blocked Message

The message to show if an IP address match occurs. Leave blank if you want nothing to show.

Message Style

You can wrap the message in a styled box, or you can select None to output the message as is.

Keyword Blocklist

The Keyword Blocklist setting allows you to specify keywords that will checked against when the form is submitted. If a keyword is found the form will be invalidated and invalid feedback will be shown on the invalid field.

The keyword matching is case-insensitive, meaning it doesn’t matter whether the word is in uppercase or lowercase.

To avoid false positives, the system performs whole word matching only. For example, if “ass” is a blocked keyword, it will not trigger on safe words like “class” or “passionate.” This helps ensure that valid submissions aren’t mistakenly flagged.

If you need more control with keyword matching, consider using the wsf_submit_field_validate filter hook.

Enable

When checked, limit by keyword blocklist will be enabled.

Keywords

To add a keyword to block:

1. Click the Add icon.
2. Enter a keyword.
3. Repeat this for each keyword you want to add.

You can also bulk specify keywords by using the wsf_submit_limit_keywords WordPress filter hook.

Invalid Feedback Message

The invalid feedback message to show on a field if it contains a blocked keyword. Leave blank if you want to show the default invalid feedback for that field.

Honeypot

Honeypot spam protection works by adding a hidden field on your form that is intended to fool spam bots into thinking they need to complete that field. If completed the email is rejected.

If you enable this setting, WS Form will automatically add Honeypot protection to your form. There is nothing else you need to do!

Akismet

Akismet provides WordPress with the ability to check comments and form submissions against their global database of spam. WS Form PRO is fully integrated with the popular Akismet spam check plugin and provides a convenient and effective way of tackling form submissions containing spam content.

Learn how to protect your forms with Akismet.

AbuseIPDB

AbuseIPDB checks the visitor’s IP address against a global database of reported abusive IPs. This section appears when AbuseIPDB support is available in WS Form.

Learn how to protect your forms with AbuseIPDB.

Settings

Spam Threshold

If your form is configured to check for spam (e.g. AbuseIPDB, Akismet or reCAPTCHA V3), each submission will be given a score between 0 (Not spam) and 100 (Blatant spam). Use this setting to determine the minimum score that will move a submission into the spam folder.

Tracking

The tracking tab contains features related to tracking your visitors. These are disabled by default to respect privacy regulations.

Google Events

This feature is only available in WS Form PRO.

WS Form can fire events at Google Tag Manager and Google Analytics levels. Learn More.

Note that WS Form PRO does not install any Google tags for you. You should do that with an additional plugin or embed it in your theme code.

Enable

When checked, event firing will be enabled.

Form

Enable this to fire an event when a form is submitted.

Tabs

Enable this to fire an event when a tab is clicked. One event is fired per tab per form session.

Fields

Enable this to fire an event when a user interacts with a field. One event is fired per field per form session.

Tracking

When a form is saved or submitted, WS Form can store a wealth of tracking information along with that form to help you gain a better understanding of your audience.

The available tracking settings can be found here.

Geo

This feature is only available in WS Form PRO.

Enable

If checked, WS Form will perform a client-side geolocation lookup by IP and will map the results to any fields configured below.

Geolocation Mapping

Map geolocation elements (such as city, region, country, latitude/longitude, and more) to fields in your form.

Learn more about geolocation lookup by IP.

Limit

This feature is only available in WS Form PRO.

By Submission Count

Limit by Submission Count

Check this setting to enable the limit by submission count features.

Maximum Count

Enter the maximum number of submissions permitted. After this limit is reached the Limit Reached Message will be displayed, or the form will simply be hidden if the Limit Reached Message is empty.

Per Logged In User

If enabled, the maximum count is limited per logged in user.

Duration

The duration setting allows you to determine over which period the maximum count will be counted. If this is set to All Time, the form will keep displaying until the maximum count is exhausted. If you choose a time duration setting, the submission count will be throttled to the maximum count within the chosen time duration.

Limit Reached Message

Enter the message you would like to display when the maximum count limit is reached. If you leave this blank, the form will be hidden when the limit is reached.

Message Style

You can wrap the message in a styled box, or you can select None to output the message as is.

By Schedule

The By Schedule options allow you to determine a start and end date for when the form is shown on your website.

Note that scheduling is ignored if you are previewing a form. To test this feature you should test the form on a public facing page.

Schedule Start

Enable this setting to set a scheduled start date/time for your form.

Start Date/Time

The date and time from which the form should become available.

Before Message

Enter the message you would like to display if the start date has not yet been reached.

Before Message Style

You can wrap the message in a styled box, or you can select None to output the message as is.

Schedule End

Enable this setting to set a scheduled end date/time for your form.

End Date/Time

The date and time after which the form should no longer be available.

After Message

Enter the message you would like to display if the end date has passed.

After Message Style

You can wrap the message in a styled box, or you can select None to output the message as is.

By User

The By User options allow you to choose which user status can access the form.

User Status

Choose from one of the options to determine who can access the form:

• Any
• Is Logged In
• Is Logged Out
• Has User Role or Capability

If you choose Has User Role or Capability, additional settings will appear that enable you to choose one or more roles or capabilities.

Type

Style of message to use if the user does not meet the user status condition. Choose from None, Success, Information, Warning, or Danger.

Message

Message shown if the user does not meet the user status condition. Leave blank to hide the form.

Loader

This feature is only available in WS Form PRO.

If enabled, a loader will be shown when certain form events trigger. It can also be shown via conditional logic. Learn more about loaders.

Enable

Check this setting to enable the form loader.

Sprite

Type

Choose the type of loader sprite to show, or select Custom HTML to provide your own markup.

Custom HTML

Enter custom HTML for the loader sprite. This setting appears if Type is set to Custom HTML.

Size (Pixels)

The size of the loader sprite in pixels.

Color

The color of the loader sprite.

Opacity

The opacity of the loader sprite.

Accent Color

The accent color used by some loader sprite types.

Accent Opacity

The opacity of the accent color.

Border Width (Pixels)

The border width of the loader sprite in pixels.

Always Visible

If checked, WS Form will attempt to keep the loader sprite always visible. This feature is useful for very long forms.

Text

Visible

If enabled, text will be shown beneath the loader sprite.

Text

Text shown beneath the sprite. We recommend using a phrase suitable for accessibility readers.

Overlay

Color

The color of the loader overlay.

Opacity

The opacity of the loader overlay.

Cursor

The cursor style shown while the loader is visible.

Timing

Animation Duration

How long one animation cycle of the loader sprite takes.

Fade-in Duration

How long the loader takes to fade in.

Fade-out Duration

How long the loader takes to fade out.

Events

Choose which events show the loader. Each enabled event can also have a delay.

Submit

Show the loader when the form is submitted.

Save

Show the loader when the form is saved.

Action

Show the loader when an action runs.

Render

Show the loader when the form is rendered.

Geolocate

Show the loader when geolocation is running.

Conversational

This feature is only available in WS Form PRO.

To learn more about Conversational Forms click here.

Enable

If checked, this form will be made available in a conversational format.

Preview

Preview the conversational version of your form.

Styling

Style

Choose which style to use for the conversational form. This setting appears when the WS Form styler is enabled.

Permalink

URL Slug

The last part of the conversational form URL.

Navigation

Enable

Show the navigation bar at the bottom of the page.

Progress Help

Help text to show alongside the navigation progress bar. You can use #progress_percent to inject the current progress percentage.

Scroll Duration (ms)

Duration in milliseconds for scrolling between sections.

Translation

This tab will appear if you have a supported translation plugin installed (for example Polylang).

Woo

This tab will appear if you have the WS Form PRO Product Integrations extension for WooCommerce installed.