Ninja Forms

Support Center

Are you using Ninja Forms 3.0? That documentation is located here.

Building Your Form

Last Updated: Aug 09, 2016 04:33PM EDT

Table of Contents

  1. Build Your Form
  2. Calculations
  3. Settings
  4. Preview
  5. Submissions

[Jump to top]

Build Your Form

When you create a new form, you will be instantly placed in the "Build Your Form" tab. Here you will select the types of fields you want in your form, set their options, and place them in the order you want them.

In this document I’ll share all the various default options that are available for the different types of field elements you can include in your form. 

It’s important to note that extensions can add additional settings beyond the ones that are included with Ninja Forms. If you are a developer this can be an extremely powerful tool at you disposal.

When you first load the page you will see a side bar loaded with an assortment of fields you can use. New fields can also be added by extensions.

In order to add a field to your form simply click the field name in the sidebar and it will automatically be added to your form and the settings panel will be opened for you to configure based on your needs. Some of these options are available for all fields while some are specific to certain field types.

Basic Field Settings

The most commonly used options are the only ones initially visible when adding a new field.

  • Field Label - The user viewable label for the field
  • Label Position - Position of the label in relation to the actual input
    • Left of Element
    • Above Element
    • Below Element
    • Right of Element
    • Inside Element
  • Placeholder - HTML5 feature allowing temporary text to appear in an input element util the user places their cursor in the element

Restriction Settings

These settings deal with restricting in some way the data users can input into your field on field completion or form submission.

  • Validate as an email address? - Checks to make sure the field input is formatted as a proper email address. 
  • Disable Input - Does not allow the user to modify the value of the field
  • Required - Field must contain a value before the form can be submit
  • Input Mask - This option gives to the ability to assign a default input mask or write a custom one to guide or restrict the way a user can fill in a field

  • Limit Input - Set a limit on the number of words or characters your users can input in a field.  In the "Text to appear after character/word counter" you can customize the user message notifying the user of the limitation

Calculation Settings

  • Include in the auto-total? (if enabled) - Adds the calculation value of this field to a running auto total for your form.  This is the only option available in non-calculation field types.

Advanced Settings

  • Default Value - Sets a default value to appear when the field is loaded

As the option described this give you the ability to assign a value to a field prior to anyone filling out the form.

Help Text and Field Description

  • Show Help Text - If you want to add a little more information in a helpful tool-tip you can enable this option.
  • Add description – Adds a helpful user note under your field.

Textbox Specific Options

These option are specific to single line text boxes and all but one is not an email specific option.


  • Datepicker – Easily turn this field into a date field with a datepicker pop-up.
  • Validate as an email address? – Select this option if you want the data validated as a proper email address.
  • This is the users state – Used to validate states of the US or other countries against payment processing solutions like PayPal or Stripe.

List Element Specific Options

  • Expand / Collapse Options - View or add to the current list options
  • Show option values  – Lets you specify a different programmatic value then the label.  If this is unchecked, the programmatic value will be the same as the label.  The “Value” is what will be saved in your database.
  • Label – The user readable list selector.
  • Value – The value that will be saved in your database when you user picks the label on the left.  If it is set to an email address, for example, you can send email notifications based on this selection with our new notifications system.
  • This is the calculation value of the field -  See our basic calculations tutorial for more information on how to use this field.

For list items you have the option of selecting whether you want to use a drop-down, radio buttons, multi-select, or check-boxes. You can either assign just a Label for each option of a Label / Value pair. This is list is also easily sortable.

Textarea Specific Options

  • Show Rich Text Editor  – Adds the ability to activate the WordPress rich text editor on your form for users to have the ability to add HTML elements in their form response.
  • Show Media Upload Button – Adds a media upload button only for logged in administrators of your form.  This is a WordPress restriction to be locked down to admins only.
  • Disable Rich Text Editor on Mobile  – Makes your textarea a plain text area on mobile devices

Admin Label

This value is not seen by the user. It replaces the label ONLY for submissions in your WordPress dashboard and the exported CSV.  This allows you to create a long/complex label for your users when interacting with your form, but a short, concise label for sorting your data on the back end.


Password Settings

This gives you the ability to add a little security verification to your password field with options like a strength indicator and a additional verification password box.


Textarea - Layout Element field

The textarea field is a field without any user input. This field accepts HTML input that will display to the user on the front end.


A frequent request is for a scroll box that contains a terms and conditions field. This can be accomplished with a textarea field containing the appropriate HTML

[Jump to top]

Google reCAPTCHA

To use Google's reCAPTCHA, a Google account is required.  You can sign up for one here.
  1. Go to
  2. Click "Get reCAPTCHA" in the top right
  3. Register your site

  4. After clicking "Register" make a note of your "Site" and "Secret" keys
  5. Input those keys into Ninja Forms under Forms -> Settings -> reCAPTCHA
  6. That's it!  Now, simply add the reCAPTCHA field to your form in the form builder and you're good to go!

[Jump to top]

Basic Calculations


Creating a basic calculation form with Ninja Forms is very simple. More detailed instructions after the video.

Step 1 – Adding Fields

**Note that text layout elements are not able to be used as a part of calculation in any way…they are static only

Before we calculate anything, we’ll need some numbers to crunch. Pretty much any kind of form field can be used for calculation purposes. For example, you could add a list field and assign a “calc” number to each of your list options. If you wanted to add or subtract a value whenever a user checked or unchecked a checkbox, you can add calc numbers to each of those. You can even add a plain old textbox and use that to get numbers from your users.

Keep in mind that in each of the examples above, if you wanted to use “automatic” calculation, which we’ll talk about below, you’ll need to check the box that says: “Include in the auto-total? (If enabled).”

If you are creating an order or customization form, you’ll want to make sure that the box marked: “Include in payment details list?” is checked. This tells Ninja Forms that the particular field is an option that affects the total cost.

Step 2 – Adding a calculation field

Now that you have your other fields added, you can decide what kind of calculation field you want to add.

If you all you want is a field that totals your items (adds them all together), then all you need to do is add the “Total” field from the Payment Fields sidebar. (If you don’t see that sidebar, make sure that your version of Ninja Forms is at least 2.2.30.)

That’s it.  If you want, you can add a Tax and Sub Total field as well.

You’re done. 

If you want to customize your  calculation fields or add something a little more complex, keep on reading.

Step 2 – Setting up your calculation field

Calculation field settings:

  • Name – Should be a unique, programmatic name. Something like my_calc_field is good, while My Calc Field isn’t. (Optional)
  • Default Value – The number that this field has before any actions are taken. There shouldn’t be anything but numbers here. (optional)
  • Display Options
    • Output Calculation As – This dropdown will let you change how your calculation field is shown on the front-end.
      • - None – Just as the name implies, nothing will be shown to the front-end user.
      • Textbox – This is the default setting. It outputs a disabled textbox on the front-end; the user can see the value, but can’t edit it.
        • Label – What label should be given to the calculation textbox.
        • Label Position – Where should the label be shown in relation to the textbox.
        • Disable input – By default, this is checked. If you want, you can allow users to directly manipulate the calculation. This is an advanced feature.
      • HTML – This is a more advanced setting, but it will let you style your output however you’d like. The string [ninja_forms_calc] will be searched for in the HTML and replaced with the proper values.
  • Calculation Method – What kind of calculation do you want, and how do you want it performed?
    • Automatically Total Calculation Values – This is the default setting. It adds together all the fields that are set as “Include in the auto-total? (If enabled).”  NOTE: DO NOT check "Include in the auto total?" on a calculation field using this calculation method or it can cause your JavaScript to break or a PHP error when submitting the form.
    • Specify Operations And Fields – This is a more advanced setting, but it allows you to add operations and select fields from your form with which to carry those operations out.
    • Use An Equation – This is the most advanced setting. You can give specific instructions in the form of an equation that references fields in your form. Stuff like field_24 + field_54 / ( field_4 * 15 )
  • Number of Decimal Places – How many decimals should this calculation field round to? The default is 2.

[Jump to top]

Plugin Settings

When you first install and activate Ninja Forms, it will create a new menu item near the bottom of you main WordPress admin menu. By default Ninja Forms doesn't have a lot of settings because most options are chosen on a per form basis. However, as you install new Ninja Forms Extensions, new options and even entirely new tabs may be added to the plugin settings. Let’s take a look at the settings you will see on a clean Ninja Forms installation with no additional extensions.

General Tab

This tab tells you the current version of Ninja Forms in your install as well as provide two settings.

  • Date Format – This lets you select the way you want dates to be displayed and saved in the database.
  • Currency Symbol – Here you can select a currency symbol when using the masked input options on any of your Ninja Forms fields.

Labels Tab

This tab allows you to set the default text that appears during form display or during particular events as users are filling out your forms.

  • Required Field Label – This appears at the top of every form that includes a required field. Change it or leave it blank to not display this message at all.
  • Required Field Symbol – This symbol can be changed to anything. It appears next to fields that you have selected as required.
  • Error message given if all required fields are not complete – This shows at the top of your form when…well…you know.
  • Required Field Error – This message will appear beneath each required field that was not filled out.
  • Anti-spam error message – This message will appear at the top of your form if the anti-spam question is answered incorrectly.
  • Please enter a valid email address – This message is displayed if the user does not enter a valid email address. Valid here refers to the structure, not whether the email address actually exists.
  • Ajax submitting message – When a form is being submitted via AJAX, this message appears at the top of the form give you users an indication that the form is being submitted.

Licenses Tab

Here you will put the license keys for any Ninja Forms extensions you have purchased and installed from

[Jump to top]

Form Settings

When you first click to add or edit a form you will be put immediately on the "Build your Form" tab to begin building your form.  To change settings affecting the entire form and not individual fields, click on the "Settings" tab.

Display Settings

Here you can edit the way your form is named, displayed, or submit.

  • Display Form Title – Check this option to display the title of the form above it when the form is displayed on your page.
  • Require user to be logged in to view form – Check this option to only allow members of your site to view the form.
  • Add form to this page – Here you can select to automatically add your form to the end of a specific WordPress page. If you want more control over where the form is added to a page or posts content then use the ninja_forms_display_form shortcode.
  • Submit via ajax (without page reload) – Check this option if you want your form to be processed without the page reloading.
  • Clear successfully completed form – Check this box if you do not want the data the user submitted to remain in the form after the form has been successfully submitted.
  • Hide successfully completed form – Check this box if you do not want the form to remain on the page after a form has been successfully submitted.

Restriction Settings

Here you can edit basic restrictions for your form such as a submissions limit, or to only show the form to logged in users.

  • Require user to be logged in to view form - Users not logged into your site will not see the form...the will instead see the message you place in "Not Logged In Message"
  • Not Logged-In Message - The message you place here will be displayed to users who view your form without being logged in if "Require user to be logged in to view form" is checked
  • Limit submissions – The form can only have a total number of submissions less than or equal to the number specified here.  This is per form, not per user.  There is currently not a way to limit forms per user.
  • Limit reached message – A message to display to users if your form has “shut down” as a result of the submission limit being reached.

[Jump to top]


This button will allow you to preview the form live on your site on the "draft" mode "ninja_forms_preview_page". DO NOT DELETE this page, or preview functionality will not work correctly. To restore it if yours has been deleted, simply deactivate/reactivate Ninja Forms.

[Jump to top]


This button allows you to view the forms submissions from the form editor.

Contact Us
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found